@naturalcycles/js-lib 14.255.0 → 14.256.0

package/dist/bot.d.ts

@@ -0,0 +1,60 @@
+export interface BotDetectionServiceCfg {
+    /**
+     * Defaults to false.
+     * If true - the instance will memoize (remember) the results of the detection
+     * and won't re-run it.
+     */
+    memoizeResults?: boolean;
+    /**
+     * Defaults to false.
+     * If set to true: `getBotReason()` would return BotReason.CDP if CDP is detected.
+     * Otherwise - `getBotReason()` will not perform the CDP check.
+     */
+    treatCDPAsBotReason?: boolean;
+}
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+export declare class BotDetectionService {
+    cfg: BotDetectionServiceCfg;
+    constructor(cfg?: BotDetectionServiceCfg);
+    private botReason;
+    private cdp;
+    isBotOrCDP(): boolean;
+    isBot(): boolean;
+    /**
+     * Returns null if it's not a Bot,
+     * otherwise a truthy BotReason.
+     */
+    getBotReason(): BotReason | null;
+    private detectBotReason;
+    /**
+     * CDP stands for Chrome DevTools Protocol.
+     * This function tests if the current environment is a CDP environment.
+     * If it's true - it's one of:
+     *
+     * 1. Bot, automated with CDP, e.g Puppeteer, Playwright or such.
+     * 2. Developer with Chrome DevTools open.
+     *
+     * 2 is certainly not a bot, but unfortunately we can't distinguish between the two.
+     * That's why this function is not part of `isBot()`, because it can give "false positive" with DevTools.
+     *
+     * Based on: https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+     */
+    isCDP(): boolean;
+    private detectCDP;
+}
+export declare enum BotReason {
+    NoNavigator = 1,
+    NoUserAgent = 2,
+    UserAgent = 3,
+    WebDriver = 4,
+    EmptyLanguages = 6,
+    /**
+     * This is when CDP is considered to be a reason to be a Bot.
+     * By default it's not.
+     */
+    CDP = 8
+}

package/dist/bot.js

@@ -0,0 +1,129 @@
+"use strict";
+// Relevant material:
+// https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotReason = exports.BotDetectionService = void 0;
+const env_1 = require("./env");
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+class BotDetectionService {
+    constructor(cfg = {}) {
+        this.cfg = cfg;
+    }
+    isBotOrCDP() {
+        return !!this.getBotReason() || this.isCDP();
+    }
+    isBot() {
+        return !!this.getBotReason();
+    }
+    /**
+     * Returns null if it's not a Bot,
+     * otherwise a truthy BotReason.
+     */
+    getBotReason() {
+        if (this.cfg.memoizeResults && this.botReason !== undefined) {
+            return this.botReason;
+        }
+        this.botReason = this.detectBotReason();
+        return this.botReason;
+    }
+    detectBotReason() {
+        // SSR - not a bot
+        if ((0, env_1.isServerSide)())
+            return null;
+        const { navigator } = globalThis;
+        if (!navigator)
+            return BotReason.NoNavigator;
+        const { userAgent } = navigator;
+        if (!userAgent)
+            return BotReason.NoUserAgent;
+        if (/bot|headless|electron|phantom|slimer/i.test(userAgent)) {
+            return BotReason.UserAgent;
+        }
+        if (navigator.webdriver) {
+            return BotReason.WebDriver;
+        }
+        // Kirill: commented out, as it's no longer seems reliable,
+        // e.g generates false positives with latest Android clients (e.g. Chrome 129)
+        // if (navigator.plugins?.length === 0) {
+        //   return BotReason.ZeroPlugins // Headless Chrome
+        // }
+        if (navigator.languages === '') {
+            return BotReason.EmptyLanguages; // Headless Chrome
+        }
+        // isChrome is true if the browser is Chrome, Chromium or Opera
+        // this is "the chrome test" from https://intoli.com/blog/not-possible-to-block-chrome-headless/
+        // this property is for some reason not present by default in headless chrome
+        // Kirill: criterium removed due to false positives with Android
+        // if (userAgent.includes('Chrome') && !(globalThis as any).chrome) {
+        //   return BotReason.ChromeWithoutChrome // Headless Chrome
+        // }
+        if (this.cfg.treatCDPAsBotReason && this.detectCDP()) {
+            return BotReason.CDP;
+        }
+        return null;
+    }
+    /**
+     * CDP stands for Chrome DevTools Protocol.
+     * This function tests if the current environment is a CDP environment.
+     * If it's true - it's one of:
+     *
+     * 1. Bot, automated with CDP, e.g Puppeteer, Playwright or such.
+     * 2. Developer with Chrome DevTools open.
+     *
+     * 2 is certainly not a bot, but unfortunately we can't distinguish between the two.
+     * That's why this function is not part of `isBot()`, because it can give "false positive" with DevTools.
+     *
+     * Based on: https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+     */
+    isCDP() {
+        if (this.cfg.memoizeResults && this.cdp !== undefined) {
+            return this.cdp;
+        }
+        this.cdp = this.detectCDP();
+        return this.cdp;
+    }
+    detectCDP() {
+        if ((0, env_1.isServerSide)())
+            return false;
+        let cdpCheck1 = false;
+        try {
+            /* eslint-disable */
+            // biome-ignore lint/suspicious/useErrorMessage: ok
+            const e = new window.Error();
+            window.Object.defineProperty(e, 'stack', {
+                configurable: false,
+                enumerable: false,
+                // biome-ignore lint/complexity/useArrowFunction: ok
+                get: function () {
+                    cdpCheck1 = true;
+                    return '';
+                },
+            });
+            // This is part of the detection and shouldn't be deleted
+            window.console.debug(e);
+            /* eslint-enable */
+        }
+        catch { }
+        return cdpCheck1;
+    }
+}
+exports.BotDetectionService = BotDetectionService;
+var BotReason;
+(function (BotReason) {
+    BotReason[BotReason["NoNavigator"] = 1] = "NoNavigator";
+    BotReason[BotReason["NoUserAgent"] = 2] = "NoUserAgent";
+    BotReason[BotReason["UserAgent"] = 3] = "UserAgent";
+    BotReason[BotReason["WebDriver"] = 4] = "WebDriver";
+    // ZeroPlugins = 5,
+    BotReason[BotReason["EmptyLanguages"] = 6] = "EmptyLanguages";
+    // ChromeWithoutChrome = 7,
+    /**
+     * This is when CDP is considered to be a reason to be a Bot.
+     * By default it's not.
+     */
+    BotReason[BotReason["CDP"] = 8] = "CDP";
+})(BotReason || (exports.BotReason = BotReason = {}));

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './abort';
 export * from './array/array.util';
 export * from './array/range';
+export * from './bot';
 export * from './datetime/dateInterval';
 export * from './datetime/localDate';
 export * from './datetime/localTime';

package/dist/index.js

@@ -5,6 +5,7 @@ const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./abort"), exports);
 tslib_1.__exportStar(require("./array/array.util"), exports);
 tslib_1.__exportStar(require("./array/range"), exports);
+tslib_1.__exportStar(require("./bot"), exports);
 tslib_1.__exportStar(require("./datetime/dateInterval"), exports);
 tslib_1.__exportStar(require("./datetime/localDate"), exports);
 tslib_1.__exportStar(require("./datetime/localTime"), exports);

package/dist-esm/bot.js

@@ -0,0 +1,125 @@
+// Relevant material:
+// https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+import { isServerSide } from './env';
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+export class BotDetectionService {
+    constructor(cfg = {}) {
+        this.cfg = cfg;
+    }
+    isBotOrCDP() {
+        return !!this.getBotReason() || this.isCDP();
+    }
+    isBot() {
+        return !!this.getBotReason();
+    }
+    /**
+     * Returns null if it's not a Bot,
+     * otherwise a truthy BotReason.
+     */
+    getBotReason() {
+        if (this.cfg.memoizeResults && this.botReason !== undefined) {
+            return this.botReason;
+        }
+        this.botReason = this.detectBotReason();
+        return this.botReason;
+    }
+    detectBotReason() {
+        // SSR - not a bot
+        if (isServerSide())
+            return null;
+        const { navigator } = globalThis;
+        if (!navigator)
+            return BotReason.NoNavigator;
+        const { userAgent } = navigator;
+        if (!userAgent)
+            return BotReason.NoUserAgent;
+        if (/bot|headless|electron|phantom|slimer/i.test(userAgent)) {
+            return BotReason.UserAgent;
+        }
+        if (navigator.webdriver) {
+            return BotReason.WebDriver;
+        }
+        // Kirill: commented out, as it's no longer seems reliable,
+        // e.g generates false positives with latest Android clients (e.g. Chrome 129)
+        // if (navigator.plugins?.length === 0) {
+        //   return BotReason.ZeroPlugins // Headless Chrome
+        // }
+        if (navigator.languages === '') {
+            return BotReason.EmptyLanguages; // Headless Chrome
+        }
+        // isChrome is true if the browser is Chrome, Chromium or Opera
+        // this is "the chrome test" from https://intoli.com/blog/not-possible-to-block-chrome-headless/
+        // this property is for some reason not present by default in headless chrome
+        // Kirill: criterium removed due to false positives with Android
+        // if (userAgent.includes('Chrome') && !(globalThis as any).chrome) {
+        //   return BotReason.ChromeWithoutChrome // Headless Chrome
+        // }
+        if (this.cfg.treatCDPAsBotReason && this.detectCDP()) {
+            return BotReason.CDP;
+        }
+        return null;
+    }
+    /**
+     * CDP stands for Chrome DevTools Protocol.
+     * This function tests if the current environment is a CDP environment.
+     * If it's true - it's one of:
+     *
+     * 1. Bot, automated with CDP, e.g Puppeteer, Playwright or such.
+     * 2. Developer with Chrome DevTools open.
+     *
+     * 2 is certainly not a bot, but unfortunately we can't distinguish between the two.
+     * That's why this function is not part of `isBot()`, because it can give "false positive" with DevTools.
+     *
+     * Based on: https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+     */
+    isCDP() {
+        if (this.cfg.memoizeResults && this.cdp !== undefined) {
+            return this.cdp;
+        }
+        this.cdp = this.detectCDP();
+        return this.cdp;
+    }
+    detectCDP() {
+        if (isServerSide())
+            return false;
+        let cdpCheck1 = false;
+        try {
+            /* eslint-disable */
+            // biome-ignore lint/suspicious/useErrorMessage: ok
+            const e = new window.Error();
+            window.Object.defineProperty(e, 'stack', {
+                configurable: false,
+                enumerable: false,
+                // biome-ignore lint/complexity/useArrowFunction: ok
+                get: function () {
+                    cdpCheck1 = true;
+                    return '';
+                },
+            });
+            // This is part of the detection and shouldn't be deleted
+            window.console.debug(e);
+            /* eslint-enable */
+        }
+        catch { }
+        return cdpCheck1;
+    }
+}
+export var BotReason;
+(function (BotReason) {
+    BotReason[BotReason["NoNavigator"] = 1] = "NoNavigator";
+    BotReason[BotReason["NoUserAgent"] = 2] = "NoUserAgent";
+    BotReason[BotReason["UserAgent"] = 3] = "UserAgent";
+    BotReason[BotReason["WebDriver"] = 4] = "WebDriver";
+    // ZeroPlugins = 5,
+    BotReason[BotReason["EmptyLanguages"] = 6] = "EmptyLanguages";
+    // ChromeWithoutChrome = 7,
+    /**
+     * This is when CDP is considered to be a reason to be a Bot.
+     * By default it's not.
+     */
+    BotReason[BotReason["CDP"] = 8] = "CDP";
+})(BotReason || (BotReason = {}));

package/dist-esm/index.js

@@ -1,6 +1,7 @@
 export * from './abort';
 export * from './array/array.util';
 export * from './array/range';
+export * from './bot';
 export * from './datetime/dateInterval';
 export * from './datetime/localDate';
 export * from './datetime/localTime';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.255.0",
+  "version": "14.256.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/bot.ts

@@ -0,0 +1,155 @@
+// Relevant material:
+// https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+
+import { isServerSide } from './env'
+
+export interface BotDetectionServiceCfg {
+  /**
+   * Defaults to false.
+   * If true - the instance will memoize (remember) the results of the detection
+   * and won't re-run it.
+   */
+  memoizeResults?: boolean
+
+  /**
+   * Defaults to false.
+   * If set to true: `getBotReason()` would return BotReason.CDP if CDP is detected.
+   * Otherwise - `getBotReason()` will not perform the CDP check.
+   */
+  treatCDPAsBotReason?: boolean
+}
+
+/**
+ * Service to detect bots and CDP (Chrome DevTools Protocol).
+ *
+ * @experimental
+ */
+export class BotDetectionService {
+  constructor(public cfg: BotDetectionServiceCfg = {}) {}
+
+  // memoized results
+  private botReason: BotReason | null | undefined
+  private cdp: boolean | undefined
+
+  isBotOrCDP(): boolean {
+    return !!this.getBotReason() || this.isCDP()
+  }
+
+  isBot(): boolean {
+    return !!this.getBotReason()
+  }
+
+  /**
+   * Returns null if it's not a Bot,
+   * otherwise a truthy BotReason.
+   */
+  getBotReason(): BotReason | null {
+    if (this.cfg.memoizeResults && this.botReason !== undefined) {
+      return this.botReason
+    }
+
+    this.botReason = this.detectBotReason()
+    return this.botReason
+  }
+
+  private detectBotReason(): BotReason | null {
+    // SSR - not a bot
+    if (isServerSide()) return null
+    const { navigator } = globalThis
+    if (!navigator) return BotReason.NoNavigator
+    const { userAgent } = navigator
+    if (!userAgent) return BotReason.NoUserAgent
+
+    if (/bot|headless|electron|phantom|slimer/i.test(userAgent)) {
+      return BotReason.UserAgent
+    }
+
+    if (navigator.webdriver) {
+      return BotReason.WebDriver
+    }
+
+    // Kirill: commented out, as it's no longer seems reliable,
+    // e.g generates false positives with latest Android clients (e.g. Chrome 129)
+    // if (navigator.plugins?.length === 0) {
+    //   return BotReason.ZeroPlugins // Headless Chrome
+    // }
+
+    if ((navigator.languages as any) === '') {
+      return BotReason.EmptyLanguages // Headless Chrome
+    }
+
+    // isChrome is true if the browser is Chrome, Chromium or Opera
+    // this is "the chrome test" from https://intoli.com/blog/not-possible-to-block-chrome-headless/
+    // this property is for some reason not present by default in headless chrome
+    // Kirill: criterium removed due to false positives with Android
+    // if (userAgent.includes('Chrome') && !(globalThis as any).chrome) {
+    //   return BotReason.ChromeWithoutChrome // Headless Chrome
+    // }
+
+    if (this.cfg.treatCDPAsBotReason && this.detectCDP()) {
+      return BotReason.CDP
+    }
+
+    return null
+  }
+
+  /**
+   * CDP stands for Chrome DevTools Protocol.
+   * This function tests if the current environment is a CDP environment.
+   * If it's true - it's one of:
+   *
+   * 1. Bot, automated with CDP, e.g Puppeteer, Playwright or such.
+   * 2. Developer with Chrome DevTools open.
+   *
+   * 2 is certainly not a bot, but unfortunately we can't distinguish between the two.
+   * That's why this function is not part of `isBot()`, because it can give "false positive" with DevTools.
+   *
+   * Based on: https://deviceandbrowserinfo.com/learning_zone/articles/detecting-headless-chrome-puppeteer-2024
+   */
+  isCDP(): boolean {
+    if (this.cfg.memoizeResults && this.cdp !== undefined) {
+      return this.cdp
+    }
+
+    this.cdp = this.detectCDP()
+    return this.cdp
+  }
+
+  private detectCDP(): boolean {
+    if (isServerSide()) return false
+    let cdpCheck1 = false
+    try {
+      /* eslint-disable */
+      // biome-ignore lint/suspicious/useErrorMessage: ok
+      const e = new window.Error()
+      window.Object.defineProperty(e, 'stack', {
+        configurable: false,
+        enumerable: false,
+        // biome-ignore lint/complexity/useArrowFunction: ok
+        get: function () {
+          cdpCheck1 = true
+          return ''
+        },
+      })
+      // This is part of the detection and shouldn't be deleted
+      window.console.debug(e)
+      /* eslint-enable */
+    } catch {}
+    return cdpCheck1
+  }
+}
+
+export enum BotReason {
+  NoNavigator = 1,
+  NoUserAgent = 2,
+  UserAgent = 3,
+  WebDriver = 4,
+  // ZeroPlugins = 5,
+  EmptyLanguages = 6,
+  // ChromeWithoutChrome = 7,
+  /**
+   * This is when CDP is considered to be a reason to be a Bot.
+   * By default it's not.
+   */
+  CDP = 8,
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './abort'
 export * from './array/array.util'
 export * from './array/range'
+export * from './bot'
 export * from './datetime/dateInterval'
 export * from './datetime/localDate'
 export * from './datetime/localTime'