index.js

"use strict";

const axios = require("axios")
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))

class BrokerBinREST {
    /**
     * BrokerBinREST
     * Initializes a new BrokerBinREST instance.
     *
     * **Example**:
     *
     * ```js
     * const BrokerBinREST = require("brokerbin").REST
     *
     * const bbClient = new BrokerBinREST({
     *   username: "webdevops",
     *   token: "..."
     * })
     * ```
     *
     * @name BrokerBinREST
     * @function
     * @param {Object} data The BrokerBinREST data:
     *
     *    - `username` (String): The BrokerBin username (default: `process.env.BROKERBIN_USERNAME`).
     *    - `token` (String): The BrokerBin token (default: `process.env.BROKERBIN_TOKEN`).
     *    - `api_root` (String): The BrokerBin API root (default: `https://search.brokerbin.com/api/v2`).
     *
     * @returns {BrokerBinREST} The BrokerBinREST instance.
     */
    constructor({
        username = process.env.BROKERBIN_USERNAME || "",
        token = process.env.BROKERBIN_TOKEN || "",
        api_root = "https://search.brokerbin.com/api/v2"
    } = {}) {
        this.username = username
        this.token = token
        this.api_root = api_root
    }

    /**
     * request
     * Make a request to the BrokerBin API.
     *
     * @name request
     * @function
     * @param {String} endpoint The endpoint to request.
     * @param {Object} query The query object.
     * @param {Boolean} returnData If `true`, the function will return the data. If `false`, it will return the response object.
     * @returns {Promise} The response data or the response object.
     */
    async request(endpoint, query, {
        returnData,
        retries,
        retryDelay
    } = {
        returnData: true,
        retries: BrokerBinREST.DEFAULT_RETRIES,
        retryDelay: BrokerBinREST.DEFAULT_RETRY_DELAY
    }) {
        let res;
        try {
            res = await axios({
                url: `${this.api_root}${endpoint}`,
                headers: {
                    Authorization: `Bearer ${this.token}`,
                    login: this.username,
                },
                params: query
            })
        } catch (e) {
            if (retries > 0) {
                await sleep(retryDelay)
                return this.request(endpoint, query, {
                    returnData,
                    retries: retries - 1,
                    retryDelay
                })
            }
            throw e
        }

        if (returnData) {
            const ret = res.data
            this.ratelimit_limit = ret.ratelimit_limit = +res.headers["x-ratelimit-limit"]
            this.ratelimit_remaining = ret.ratelimit_remaining = +res.headers["x-ratelimit-remaining"]
            return ret
        }

        return res
    }

    /**
     * partSearch
     * Search for parts by part number.
     *
     * **Example**
     *
     * ```js
     * // Initialize the BrokerBin instance
     * const bbClient = new BrokerBinREST({
     *    username: "webdevops",
     *    token: "..."
     * })
     *
     * // Run a search
     * bbClient.partSearch({
     *   query: "188122-B22",
     * })
     * ```
     *
     * @name partSearch
     * @function
     * @param {Object} data The search data:
     *
     *    - `query` (required) the search string, part number
     *    - `fields` db fields to search against, possible values: partsno,manufacturer,description,condition (default: partsno)
     *    - `mfg[]` filter by manufacturer
     *    - `cond[]` filter by condition
     *    - `country[]` filter by country
     *    - `region[]` filter by region
     *    - `state[]` filter by state
     *    - `size` number of results to return (default: 10)
     *    - `offset` number of results to skip (default: 0, max: 900)
     *    - `fuzziness` percentage of search terms that require matches (default: 100%)
     *    - `first` myVen show first (boost 200%)
     *    - `last` myVen show last (de-boost 90%)
     *    - `never` myVen show never (filter out)
     *    - `priced` filter priced parts only
     *    - `age` only match parts this many days old, or less
     *    - `sort[index][field]=direction` the index, field and direction (default: sort[0][_score]=desc&sort[1][age]=desc&sort[2][company.original]=asc)
     *       - where index is an integer with which the lowest number takes the highest precedence and no numbers repeat -- ex: 0, 1, 2
     *       - and where the valid sorting fields are: age, clei.original, company.original, condition, country, manufacturer, partsno.original, price, qty, region, state
     *       - and where the valid sorting directions are: asc, desc
     *
     * @returns {Promise} The response data looks like this:
     *
     *  ```js
     *  {
     *      "meta": {
     *          "total": 18,
     *          "manufacturers": [
     *              {
     *                  "key": "HP",
     *                  "doc_count": 18
     *              }
     *          ],
     *          "conditions": [
     *              {
     *                  "key": "REF",
     *                  "doc_count": 17
     *              },
     *              {
     *                  "key": "NEW",
     *                  "doc_count": 1
     *              }
     *          ],
     *          "states": [
     *              {
     *                  "key": "FL",
     *                  "doc_count": 6
     *              },
     *              {
     *                  "key": "WY",
     *                  "doc_count": 6
     *              },
     *              {
     *                  "key": "TX",
     *                  "doc_count": 2
     *              },
     *              {
     *                  "key": "KY",
     *                  "doc_count": 1
     *              },
     *              {
     *                  "key": "MN",
     *                  "doc_count": 1
     *              },
     *              {
     *                  "key": "NY",
     *                  "doc_count": 1
     *              },
     *              {
     *                  "key": "WA",
     *                  "doc_count": 1
     *              }
     *          ],
     *          "countries": [
     *              {
     *                  "key": "USA",
     *                  "doc_count": 18
     *              }
     *          ],
     *          "regions": [
     *              {
     *                  "key": "North America",
     *                  "doc_count": 18
     *              }
     *          ],
     *          "request": {
     *              "count": 33,
     *              "limit": 100
     *          }
     *      },
     *      "data": [
     *          {
     *              "company": "Techlogix USA",
     *              "country": "USA",
     *              "part": "188122-B22",
     *              "clei": "",
     *              "mfg": "HP",
     *              "cond": "REF",
     *              "description": "HP 18.2GB 15000RPM Ultra-160 SCSI 80-Pin LVD Hot-Pluggable 3.5-inch Hard Drive",
     *              "price": 0,
     *              "qty": 1,
     *              "age_in_days": 6
     *          },
     *          {
     *              "company": "Techlogix USA",
     *              "country": "USA",
     *              "part": "188122-B22",
     *              "clei": "",
     *              "mfg": "HP",
     *              "cond": "REF",
     *              "description": "HP 18.2GB 15000RPM Ultra-160 SCSI 80-Pin LVD Hot-Pluggable 3.5-inch Hard Drive",
     *              "price": 0,
     *              "qty": 1,
     *              "age_in_days": 7
     *          },
     *          "truncated..."
     *      ]
     *  }
     *  ```
     */
    async partSearch(data) {
        return this.request("/part/search", data)
    }

    /**
     * partPrefix
     * Search for parts by the beginning (or complete) of a part number.
     *
     * @name partPrefix
     * @function
     * @param {Object} data An object containing the following data:
     *
     *    - `query` (required) the search string, part number, or beginning of part number
     *    - `mfg[]` filter by manufacturer
     *    - `cond[]` filter by condition
     *    - `country[]` filter by country
     *    - `region[]` filter by region
     *    - `state[]` filter by state
     *    - `size` number of results to return (default: 10)
     *    - `offset` number of results to skip (default: 0, max: 900)
     *    - `first` myVen show first (boost 200%)
     *    - `last` myVen show last (de-boost 90%)
     *    - `never` myVen show never (filter out)
     *    - `priced` filter priced parts only
     *    - `age` only match parts this many days old, or less
     *    - `sort[index][field]=direction` the index, field and direction (default: sort[0][_score]=desc&sort[1][age]=desc&sort[2][company.original]=asc)
     *      - where index is an integer with which the lowest number takes the highest precedence and no numbers repeat -- ex: 0, 1, 2
     *      - and where valid sorting fields are: age, clei.original, company.original, condition, country, manufacturer, partsno.original, price, qty, region, state
     *      - and where valid sorting directions are: asc, desc
     *
     * @returns {Promise} The response data looks like this:
     *
     * ```js
     * {
     *    "meta": {
     *        "total": 18,
     *        "request": {
     *            "count": 16,
     *            "limit": 50
     *        },
     *        "manufacturers": [
     *            {
     *                "key": "HP",
     *                "doc_count": 18
     *            }
     *        ],
     *        "conditions": [
     *            {
     *                "key": "REF",
     *                "doc_count": 16
     *            },
     *            {
     *                "key": "NEW",
     *                "doc_count": 2
     *            }
     *        ],
     *        "states": [
     *            {
     *                "key": "FL",
     *                "doc_count": 8
     *            },
     *            {
     *                "key": "NY",
     *                "doc_count": 3
     *            },
     *            {
     *                "key": "KY",
     *                "doc_count": 2
     *            },
     *            {
     *                "key": "TX",
     *                "doc_count": 2
     *            },
     *            {
     *                "key": "WA",
     *                "doc_count": 2
     *            },
     *            {
     *                "key": "MN",
     *                "doc_count": 1
     *            }
     *        ],
     *        "countries": [
     *            {
     *                "key": "USA",
     *                "doc_count": 18
     *            }
     *        ],
     *        "regions": [
     *            {
     *                "key": "North America",
     *                "doc_count": 18
     *            }
     *        ],
     *        "price": {
     *            "count": 18,
     *            "min": 0,
     *            "max": 65,
     *            "avg": 6.833333333333333,
     *            "sum": 123
     *        },
     *        "qty": {
     *            "count": 18,
     *            "min": 1,
     *            "max": 69,
     *            "avg": 7.277777777777778,
     *            "sum": 131
     *        }
     *    },
     *    "data": [
     *        {
     *            "company": "Serverworlds.com",
     *            "country": "USA",
     *            "part": "188122-B22",
     *            "clei": "",
     *            "mfg": "HP",
     *            "cond": "REF",
     *            "description": "18.2GB U3 15K SCSI 1 hotplug",
     *            "price": 65,
     *            "qty": 69,
     *            "age_in_days": 0
     *        },
     *        {
     *            "company": "Blitz Network Solutions Inc.",
     *            "country": "USA",
     *            "part": "188122-B21",
     *            "clei": "",
     *            "mfg": "HP",
     *            "cond": "REF",
     *            "description": "HP 18.2GB 15000RPM Ultra-160 SCSI Hot-Pluggable LVD 80-Pin 3.5-inch Hard Drive 5-7 Business Days Lead Time",
     *            "price": 0,
     *            "qty": 7,
     *            "age_in_days": 0
     *        }
     *        ,{"truncated":"truncated..."}
     *    ]
     * }
     * ```
     */
    async partPrefix(data) {
        return this.request("/part/prefix", data)
    }

    /**
     * partStatsHistogram
     * Produce 90 day histogram for a single part with extended stats on price and qty.
     *
     * @name partStatsHistogram
     * @function
     * @param {Object} data An object containing the following data:
     *
     *   - `query` (required) the search string, part number
     *   - `mfg[]` filter by manufacturer
     *   - `cond[]` filter by condition
     *   - `country[]` filter by country
     *   - `region[]` filter by region
     *   - `state[]` filter by state
     *   - `never` myVen show never (filter out)
     *   - `priced` filter priced parts only
     *   - `interval` the timeframe for the historgram (day,week,month, or year)
     *   - `from` include dates greater than or equal to this date
     *   - `to` include dates less than or equal to this date
     *
     * @returns {Promise} The response data looks like this:
     *
     * ```js
     * {
     *    "meta": {
     *        "request": {
     *            "count": 19,
     *            "limit": 25
     *        },
     *        "manufacturers": [
     *            {
     *                "key": "HP",
     *                "doc_count": 182
     *            }
     *        ],
     *        "conditions": [
     *            {
     *                "key": "REF",
     *                "doc_count": 154
     *            },
     *            {
     *                "key": "NEW",
     *                "doc_count": 28
     *            }
     *        ],
     *        "states": [],
     *        "countries": [
     *            {
     *                "key": "USA",
     *                "doc_count": 182
     *            }
     *        ],
     *        "regions": [
     *            {
     *                "key": "North America",
     *                "doc_count": 182
     *            }
     *        ]
     *    },
     *    "data": [
     *        {
     *            "date": "2023-02-01 00:00:00",
     *            "price_weighted_by_qty": 32.206832871652814,
     *            "price_stats": {
     *                "count": 182,
     *                "min": 0,
     *                "max": 45,
     *                "avg": 8.131868131868131,
     *                "sum": 1480,
     *                "sum_of_squares": 57320,
     *                "variance": 248.81777563096244,
     *                "variance_population": 248.81777563096244,
     *                "variance_sampling": 250.19245947422743,
     *                "std_deviation": 15.773958781198917,
     *                "std_deviation_population": 15.773958781198917,
     *                "std_deviation_sampling": 15.817473232922742,
     *                "std_deviation_bounds": {
     *                    "upper": 39.679785694265966,
     *                    "lower": -23.416049430529704,
     *                    "upper_population": 39.679785694265966,
     *                    "lower_population": -23.416049430529704,
     *                    "upper_sampling": 39.76681459771362,
     *                    "lower_sampling": -23.503078333977353
     *                }
     *            },
     *            "qty_stats": {
     *                "count": 182,
     *                "min": 1,
     *                "max": 73,
     *                "avg": 11.901098901098901,
     *                "sum": 2166,
     *                "sum_of_squares": 113284,
     *                "variance": 480.80340538582294,
     *                "variance_population": 480.80340538582294,
     *                "variance_sampling": 483.45977779126946,
     *                "std_deviation": 21.927229769987427,
     *                "std_deviation_population": 21.927229769987427,
     *                "std_deviation_sampling": 21.98771879461963,
     *                "std_deviation_bounds": {
     *                    "upper": 55.75555844107376,
     *                    "lower": -31.953360638875953,
     *                    "upper_population": 55.75555844107376,
     *                    "lower_population": -31.953360638875953,
     *                    "upper_sampling": 55.87653649033817,
     *                    "lower_sampling": -32.07433868814036
     *                }
     *            }
     *        }
     *    ]
     * }
     * ```
     */
    async partStatsHistogram(data) {
        return this.request("/part/history/stats", data)
    }

    /**
     * rfqHistogram
     * Aggregated RFQ counts for a single part.
     *
     * @name rfqHistogram
     * @function
     * @param {Object} data An object containing the following data:
     *
     *   - `query` (required) the search string, part number
     *   - `mfg[]` filter by manufacturer
     *   - `cond[]` filter by condition
     *   - `from` include dates greater than or equal to this date
     *   - `to` include dates less than or equal to this date
     *   - `size` number of results to return (default: 10)
     *   - `offset` number of results to skip (default: 0, max: 900)
     *   - `fuzziness` percentage of search terms that require matches (default: 100%)
     *
     * @returns {Promise} The response data looks like this:
     *
     *  ```js
     *  {
     *     "meta": {
     *         "request": {
     *             "count": 19,
     *             "limit": 25
     *         },
     *         "manufacturers": [
     *             {
     *                 "key": "HP",
     *                 "doc_count": 50
     *             }
     *         ],
     *         "conditions": [
     *             {
     *                 "key": "NEW",
     *                 "doc_count": 50
     *             }
     *         ]
     *     },
     *     "data": [
     *         {
     *             "date": "2023-01-30 00:00:00",
     *             "rfqs": 5
     *         },
     *         {
     *             "date": "2023-02-06 00:00:00",
     *             "rfqs": 17
     *         },
     *         {
     *             "date": "2023-02-13 00:00:00",
     *             "rfqs": 6
     *         },
     *         {
     *             "date": "2023-02-20 00:00:00",
     *             "rfqs": 6
     *         },
     *         {
     *             "date": "2023-02-27 00:00:00",
     *             "rfqs": 7
     *         },
     *         {
     *             "date": "2023-03-06 00:00:00",
     *             "rfqs": 9
     *         }
     *     ]
     *  }
     *  ```
     */
    async rfqHistogram(data) {
        return this.request("/part/history/rfq", data)
    }

    /**
     * supplyAndDemandHistogram
     * Aggregated Search and Result counts for a single part.
     *
     * @name supplyAndDemandHistogram
     * @function
     * @param {Object} data An object containing the following data:
     *
     *    - `query` (required) the search string, part number
     *    - `mfg[]` filter by manufacturer
     *    - `age` only include parts this many days old, or less
     *    - `fuzziness` percentage of search terms that require matches (default: 100%)
     *    - `interval` the timeframe for the historgram (day,week,month, or year)
     *    - `from` include dates greater than or equal to this date
     *    - `to` include dates less than or equal to this date
     *
     * @returns {Promise} The response data looks like this:
     *
     * ```js
     * {
     *     "meta": {
     *         "request": {
     *             "count": 12,
     *             "limit": 25
     *         },
     *         "manufacturers": [
     *             {
     *                 "key": "HP",
     *                 "doc_count": 18
     *             },
     *             {
     *                 "key": "HPE",
     *                 "doc_count": 17
     *             },
     *             {
     *                 "key": "ARUBA NETWORKS",
     *                 "doc_count": 13
     *             },
     *             {
     *                 "key": "HPE - ARUBA SWITCHING",
     *                 "doc_count": 3
     *             }
     *         ]
     *     },
     *     "data": [
     *         {
     *             "date": "2023-02-01 00:00:00",
     *             "searches": 2113,
     *             "avg_result_count": 688
     *         }
     *     ]
     * }
     * ```
     */
    async supplyAndDemandHistogram(data) {
        return this.request("part/history/supply-demand", data)
    }

    /**
     * topParts
     * Aggregated search counts by part for a given mfg sorted by number of searches in descending order
     *
     * @name topParts
     * @function
     * @param {Object} data An object containing the following data:
     *
     *   - `query` (required) the search string, manufacturer
     *   - `fuzziness` percentage of search terms that require matches (default: 100%)
     *   - `from` include dates greater than or equal to this date
     *   - `to` include dates less than or equal to this date
     *   - `size` the number of parts to return
     *
     * @returns {Promise} The response data looks like this:
     *
     * ```js
     * {
     *    "meta": {
     *        "request": {
     *            "count": 19,
     *            "limit": 25
     *        }
     *    },
     *    "data": [
     *        {
     *            "part": "WS-C2960X-24PS-L",
     *            "searches": 5475
     *        },
     *        {
     *            "part": "WS-C2960X-48FPS-L",
     *            "searches": 4154
     *        },
     *        {
     *            "part": "WS-C2960X-48FPD-L",
     *            "searches": 3661
     *        },
     *        {
     *            "part": "GLC-LH-SMD",
     *            "searches": 3244
     *        },
     *        {
     *            "part": "C9300-NM-8X",
     *            "searches": 2783
     *        },
     *        {
     *            "part": "N9K-C93180YC-EX",
     *            "searches": 2442
     *        },
     *        {
     *            "part": "STACK-T1-50CM",
     *            "searches": 2410
     *        },
     *        {
     *            "part": "ASR1001-X",
     *            "searches": 2394
     *        },
     *        {
     *            "part": "C9200L-48P-4X-E",
     *            "searches": 1955
     *        },
     *        {
     *            "part": "WS-C2960X-48LPS-L",
     *            "searches": 1886
     *        }
     *    ]
     * }
     * ```
     */
    async topParts(data) {
        return this.request("/mfg/top-parts", data)
    }

    /**
     * matches
     * Find users and company who searched for an exact part number.
     *
     * @name matches
     * @function
     * @param {Object} data An object containing the following data:
     *
     *   - `query` (required) the search string, part number
     *   - `from` include matches on dates greater than or equal to this date
     *   - `never` myVen show never (filter out)
     *   - `in_stock` only include searchers who had the item in-stock when the search occurred
     *
     * @returns {Promise} The response data looks like this:
     *
     * ```js
     * {
     *    "meta": {
     *        "request": {
     *            "count": 44,
     *            "limit": 100
     *        }
     *    },
     *    "data": {
     *        "query": "c9300-nm-8x",
     *        "from": "2024-06-20",
     *        "results": {
     *            "count": 17,
     *            "matches": [
     *                {
     *                    "company_name": "Network Craze Technologies",
     *                    "company_contact": "James Froio",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 26,
     *                    "age": "51 minutes ago"
     *                },
     *                {
     *                    "company_name": "NW Remarketing",
     *                    "company_contact": "Louis Zahler",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 5,
     *                    "age": "3 hours ago"
     *                },
     *                {
     *                    "company_name": "Refub Tech",
     *                    "company_contact": "Saless Team",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 4,
     *                    "age": "4 hours ago"
     *                },
     *                {
     *                    "company_name": "Neon Devices LLC",
     *                    "company_contact": "Nohail K",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 52,
     *                    "age": "4 hours ago"
     *                },
     *                {
     *                    "company_name": "Network Integrators LTD.",
     *                    "company_contact": "Purchasing Team",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 1,
     *                    "age": "5 hours ago"
     *                },
     *                {
     *                    "company_name": "Link-US LLC",
     *                    "company_contact": "Basem Toma",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 1,
     *                    "age": "6 hours ago"
     *                },
     *                {
     *                    "company_name": "Crisp Technologies LLC",
     *                    "company_contact": "Steve Murphy",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 10,
     *                    "age": "6 hours ago"
     *                },
     *                {
     *                    "company_name": "Nordic Computer",
     *                    "company_contact": "Ozren Nezic",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 1,
     *                    "age": "11 hours ago"
     *                },
     *                {
     *                    "company_name": "Euro IT Solution LTD",
     *                    "company_contact": "Javed A.",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 2,
     *                    "age": "12 hours ago"
     *                },
     *                {
     *                    "company_name": "Knowledge Computers PTE",
     *                    "company_contact": "N/A",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 2,
     *                    "age": "12 hours ago"
     *                },
     *                {
     *                    "company_name": "Euro IT Solution LTD",
     *                    "company_contact": "Javed A.",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 2,
     *                    "age": "12 hours ago"
     *                },
     *                {
     *                    "company_name": "Units Enterprise",
     *                    "company_contact": "Andy Bryant",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 2,
     *                    "age": "1 day ago"
     *                },
     *                {
     *                    "company_name": "Units Enterprise",
     *                    "company_contact": "Jim Henderson",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 2,
     *                    "age": "1 day ago"
     *                },
     *                {
     *                    "company_name": "Units Enterprise",
     *                    "company_contact": "Jim Henderson",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 2,
     *                    "age": "1 day ago"
     *                },
     *                {
     *                    "company_name": "Knowledge Computers USA",
     *                    "company_contact": "Travis Oestreich",
     *                    "search_query": "c9300-nm-8x",
     *                    "qty": 4,
     *                    "age": "1 day ago"
     *                },
     *                {
     *                    "company_name": "Colorado Peak Technologies,Inc",
     *                    "company_contact": "Alex Myers",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 3,
     *                    "age": "1 day ago"
     *                },
     *                {
     *                    "company_name": "eGoods Supply, Inc.",
     *                    "company_contact": "Norman",
     *                    "search_query": "C9300-NM-8X",
     *                    "qty": 4,
     *                    "age": "1 day ago"
     *                }
     *            ]
     *        }
     *    }
     * }
     * ```
     *
     * ----
     *
     */
    async matches(data) {
        return this.request("/part/history/matches", data)
    }
}

BrokerBinREST.DEFAULT_RETRIES = 5
BrokerBinREST.DEFAULT_RETRY_DELAY = 15000

module.exports = BrokerBinREST