Http

Node.js HTTP

Install

npm i @botbye/node-http

yarn add @botbye/node-http

No peer dependencies — it uses the built-in Node.js http module.

Configuration

Call phishing.init once at application startup, before serving any catcher requests. Anti-phishing is identified by its own clientKey (available in your Phishing Project in the Dashboard), not the server key used by evaluate.

import { phishing } from "@botbye/node-http";

phishing.init({
  // clientKey from your Phishing Project in the Dashboard
  clientKey: "00000000-0000-0000-0000-000000000000",
});

Option	Type	Required	Description
clientKey	string	Yes	clientKey from your Phishing Project in the Dashboard
url	string	No	Override BotBye API endpoint (default: https://verify.botbye.com)
logger.level	string	No	Log level: error, warn, info, debug, log (default: info)
logger.logger	TLogger	No	Custom logger implementing { error, warn, info, debug, log }
timeouts.fetchCatcher	number	No	Timeout in milliseconds for each fetchCatcher call

Usage

Anti-phishing needs two routes on your own origin, each proxied through fetchCatcher:

SVG route — serves the SVG catcher. This is the URL your client code passes to getCatcher({ url }).

PNG route — serves the PNG that the SVG references (via innerPngUrl).

The paths are arbitrary — name the routes however you like. Pass the raw request as request and the format. For the SVG, innerPngUrl must be the absolute URL of your PNG route — the browser loads that PNG directly from your origin.

import * as http from "node:http";
import { phishing } from "@botbye/node-http";

// Absolute URL of your PNG endpoint — the SVG catcher references it through innerPngUrl.
const PNG_CATCHER_URL = "https://your-site.example/botbye-catcher.png";

const server = http.createServer(async (req, res) => {
  // SVG catcher (this URL goes into the catcher element on your pages)
  if (req.url?.startsWith("/botbye-catcher.svg")) {
    const catcher = await phishing.fetchCatcher({
      request: req,
      format: "svg",
      innerPngUrl: PNG_CATCHER_URL,
    });

    res.writeHead(catcher.status, catcher.headers);
    res.end(Buffer.from(catcher.body));
    return;
  }

  // Companion PNG the SVG above references via innerPngUrl
  if (req.url?.startsWith("/botbye-catcher.png")) {
    const catcher = await phishing.fetchCatcher({ request: req, format: "png" });

    res.writeHead(catcher.status, catcher.headers);
    res.end(Buffer.from(catcher.body));
    return;
  }

  /* your other routing */
});

We recommend embedding the SVG catcher: it is designed to keep tracking even when a phishing site copies all of your assets to its own infrastructure (the PNG route exists because the SVG catcher relies on it).

Multiple instances

phishing is a ready default instance. Use phishingFactory() to create isolated instances for multiple projects.

import { phishingFactory } from "@botbye/node-http";

const phishing = phishingFactory();
phishing.init({ clientKey: "00000000-0000-0000-0000-000000000000" });