@botbye/nest-express 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BotBye!
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,428 @@
+# @botbye/nest-express
+
+[BotBye!](https://botbye.com) integration for [NestJS](https://nestjs.com/) with [Express](https://expressjs.com/) applications.
+
+Full documentation: https://botbye.com/docs/server-side/node-js/nestjs/express
+
+## Install
+
+```bash
+npm i @botbye/nest-express
+```
+
+```bash
+yarn add @botbye/nest-express
+```
+
+Requires `@nestjs/common >= 10` and `express >= 4` as peer dependencies.
+
+## Configuration
+
+Register `BotByeModule` once in your root module:
+
+```typescript
+import { Module } from "@nestjs/common";
+import { BotByeModule } from "@botbye/nest-express";
+
+@Module({
+  imports: [
+    BotByeModule.register({
+      // Use your project server-key
+      serverKey: "00000000-0000-0000-0000-000000000000",
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### `init` options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `serverKey` | `string` | Yes | Server key from your BotBye project |
+| `url` | `string` | No | Override BotBye API endpoint (default: `https://verify.botbye.com`) |
+| `logger.level` | `"error" \| "warn" \| "info" \| "debug" \| "log"` | No | Log level (default: `"info"`) |
+| `logger.logger` | `TLogger` | No | Custom logger instance implementing `{ error, warn, info, debug, log }` |
+| `timeouts.evaluate` | `number` | No | Timeout in milliseconds for each `evaluate` call |
+| `tokenExtractor` | `(request: Request) => string \| null \| undefined` | No* | Extracts the BotBye token from the Express request. *Required when using `BotByeMiddleware` — without it the middleware skips evaluation and returns an error result. |
+
+## Usage
+
+After registering `BotByeModule`, inject `TBotByeService` using `BOTBYE_SERVICE_DI_TOKEN` to call `evaluate` from guards, controllers, or services.
+
+```typescript
+import { Controller, Post, Inject, Req, ForbiddenException } from "@nestjs/common";
+import { Request } from "express";
+import { BOTBYE_SERVICE_DI_TOKEN, TBotByeService } from "@botbye/nest-express";
+
+@Controller()
+export class AppController {
+  constructor(
+    @Inject(BOTBYE_SERVICE_DI_TOKEN) private readonly botbye: TBotByeService
+  ) {}
+
+  @Post("/api/submit")
+  async submit(@Req() req: Request) {
+    const result = await this.botbye.evaluate({
+      type: "validate",
+      request: {
+        request: req,
+        // "x-botbye-token" is an example — pass the token from wherever you store it
+        token: req.headers["x-botbye-token"] as string | null,
+      },
+    });
+
+    if (result.decision === "BLOCK") {
+      throw new ForbiddenException();
+    }
+
+    // proceed normally
+  }
+}
+```
+
+There are three event types — `validate`, `risk`, and `full` — each suited for a different layer of your application.
+
+---
+
+### `validate` — edge-level bot check
+
+Use at the edge — guard, route handler, middleware — when you just want to know: **was this request made by a bot?** No user or domain context needed.
+
+**Event fields:**
+
+```typescript
+{
+  type: "validate";
+
+  request:
+    // Option A: pass the Express request object directly — SDK extracts everything automatically
+    | { request: Request; token?: string | null }
+    // Option B: construct request info manually
+    | { ip: string; headers: Record<string, string>; requestMethod?: string | null; requestUri?: string | null; token?: string | null };
+
+  customFields?: Record<string, string>;
+
+  config?: { bypassBotValidation?: boolean | null };
+}
+```
+
+The SDK extracts IP, headers, method, and URI from the Express request automatically. You can also pass request info manually — see Option B above. The `token` is a one-time token generated by the [BotBye client-side SDK](https://botbye.com/docs/client-side/npm-module) that contains information about the user's device. Pass whatever the client sent; if no token is received, the decision will be `"BLOCK"`.
+
+```typescript
+import { Injectable, CanActivate, ExecutionContext, Inject } from "@nestjs/common";
+import { Request } from "express";
+import { BOTBYE_SERVICE_DI_TOKEN, TBotByeService } from "@botbye/nest-express";
+
+@Injectable()
+export class BotProtectionGuard implements CanActivate {
+  constructor(
+    @Inject(BOTBYE_SERVICE_DI_TOKEN) private readonly botbye: TBotByeService
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<Request>();
+
+    const result = await this.botbye.evaluate({
+      type: "validate",
+      request: {
+        request,
+        // "x-botbye-token" is an example — pass the token from wherever you store it
+        token: request.headers["x-botbye-token"] as string | null,
+      },
+    });
+
+    return result.decision !== "BLOCK";
+  }
+}
+```
+
+---
+
+### `risk` — domain-level risk scoring
+
+Use inside services that already know the user: auth, payments, account management. The purpose shifts from "is this a bot?" to **"is something suspicious happening for this user?"** — credential stuffing, account takeover, account sharing, logins from a new geo.
+
+**Event fields:**
+
+```typescript
+{
+  type: "risk";
+
+  request:
+    // Only ip is needed at this level
+    | { ip: string; headers?: Record<string, string>; requestMethod?: string | null; requestUri?: string | null; token?: string | null }
+    // Express request object also accepted if convenient
+    | { request: Request };
+
+  event: {
+    type: string;   // e.g. "login", "password_change", "checkout"
+    status: "ATTEMPTED" | "SUCCESSFUL" | "FAILED" | "UNKNOWN";
+  };
+
+  user: {
+    accountId: string;
+    username?: string | null;
+    email?: string | null;
+    phone?: string | null;
+  };
+
+  customFields?: Record<string, string>;
+  botbyeResult?: string;
+
+  config?: { bypassBotValidation?: boolean | null };
+}
+```
+
+`event` and `user` are the key fields here — they define what action is being performed and who is performing it, which is what drives the risk score. `ip` is equally important: BotBye tracks which IPs access the account to detect patterns like account sharing, credential stuffing, and suspicious geo logins. Pass it directly as `{ ip }`, or pass the Express request object if that's more convenient.
+
+```typescript
+import { Injectable, Inject } from "@nestjs/common";
+import { BOTBYE_SERVICE_DI_TOKEN, TBotByeService } from "@botbye/nest-express";
+
+@Injectable()
+export class AuthService {
+  constructor(
+    @Inject(BOTBYE_SERVICE_DI_TOKEN) private readonly botbye: TBotByeService
+  ) {}
+
+  async onLoginAttempt(ip: string, userId: string, email: string, loginSucceeded: boolean) {
+    const result = await this.botbye.evaluate({
+      type: "risk",
+      request: { ip },
+      event: {
+        type: "login",
+        status: loginSucceeded ? "SUCCESSFUL" : "FAILED",
+        // "SUCCESSFUL" | "FAILED" | "ATTEMPTED" | "UNKNOWN"
+      },
+      user: {
+        accountId: userId,
+        email,
+      },
+    });
+
+    if (result.decision === "BLOCK") {
+      // Lock account, trigger MFA, send alert, etc.
+    }
+  }
+}
+```
+
+---
+
+### `full` — edge check and domain scoring in one call
+
+Use when you have all context at once: raw request, token, user, and event. Equivalent to running `validate` and `risk` in a single call. A login endpoint is a typical example — it receives the HTTP request and immediately knows the user and outcome.
+
+**Event fields:**
+
+```typescript
+{
+  type: "full";
+
+  request:
+    | { request: Request; token?: string | null }
+    | { ip: string; headers: Record<string, string>; requestMethod?: string | null; requestUri?: string | null; token?: string | null };
+
+  event: {
+    type: string;
+    status: "ATTEMPTED" | "SUCCESSFUL" | "FAILED" | "UNKNOWN";
+  };
+
+  user: {
+    accountId: string;
+    username?: string | null;
+    email?: string | null;
+    phone?: string | null;
+  };
+
+  customFields?: Record<string, string>;
+
+  config?: { bypassBotValidation?: boolean | null };
+}
+```
+
+```typescript
+import { Injectable, Inject, ForbiddenException } from "@nestjs/common";
+import { Request } from "express";
+import { BOTBYE_SERVICE_DI_TOKEN, TBotByeService } from "@botbye/nest-express";
+
+@Injectable()
+export class AuthService {
+  constructor(
+    @Inject(BOTBYE_SERVICE_DI_TOKEN) private readonly botbye: TBotByeService
+  ) {}
+
+  async login(request: Request, email: string, password: string) {
+    const user = await this.findUser(email);
+    const loginSucceeded = user && (await this.checkPassword(user, password));
+
+    const result = await this.botbye.evaluate({
+      type: "full",
+      request: {
+        request,
+        // "x-botbye-token" is an example — pass the token from wherever you store it
+        token: request.headers["x-botbye-token"] as string | null,
+      },
+      event: {
+        type: "login",
+        status: loginSucceeded ? "SUCCESSFUL" : "FAILED",
+      },
+      user: {
+        accountId: user?.id ?? "unknown",
+        email,
+      },
+    });
+
+    if (result.decision === "BLOCK") {
+      throw new ForbiddenException();
+    }
+
+    // proceed normally
+  }
+}
+```
+
+---
+
+## Response
+
+`evaluate` always returns a `Promise<TEvaluationResult>`:
+
+```typescript
+type TEvaluationResult =
+  | {
+      decision: "ALLOW" | "BLOCK" | "CHALLENGE";
+      request_id: string;
+      risk_score: number;
+      scores: Record<string, number>;
+      signals: string[];
+      config: { bypass_bot_validation: boolean };
+    }
+  | {
+      decision: "ALLOW" | "BLOCK" | "CHALLENGE";
+      config: { bypass_bot_validation: boolean };
+      error: { message: string };
+    };
+```
+
+Check `result.decision` to decide how to handle the request:
+
+- `"ALLOW"` — request appears legitimate, proceed normally
+- `"BLOCK"` — bot or suspicious activity detected, block the request
+- `"CHALLENGE"` — uncertain, consider issuing a CAPTCHA, MFA, or additional verification step
+
+When the response contains an `error` field, BotBye could not evaluate the request (e.g. invalid server key). In that case `decision` defaults to `"ALLOW"` so that a misconfiguration does not block real users — but you should monitor and fix the underlying error.
+
+### Response examples
+
+Blocked (bot detected):
+
+```json
+{
+  "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
+  "decision": "BLOCK",
+  "risk_score": 0.95,
+  "scores": { "bot": 0.95 },
+  "signals": ["AutomationTool"],
+  "config": { "bypass_bot_validation": false }
+}
+```
+
+Allowed:
+
+```json
+{
+  "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
+  "decision": "ALLOW",
+  "risk_score": 0.05,
+  "scores": { "bot": 0.05, "ato": 0.02 },
+  "signals": [],
+  "config": { "bypass_bot_validation": false }
+}
+```
+
+Challenge:
+
+```json
+{
+  "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
+  "decision": "CHALLENGE",
+  "risk_score": 0.65,
+  "scores": { "bot": 0.65 },
+  "signals": ["SuspiciousFingerprint"],
+  "challenge": { "type": "captcha", "token": "..." },
+  "config": { "bypass_bot_validation": false }
+}
+```
+
+Invalid `serverKey`:
+
+```json
+{
+  "decision": "ALLOW",
+  "config": { "bypass_bot_validation": true },
+  "error": { "message": "[BotBye] Bad Request: Invalid Server Key" }
+}
+```
+
+## Middleware usage
+
+`BotByeMiddleware` evaluates every incoming request automatically and stores the result on the request object. Use the `@BotByeResponse()` parameter decorator to access the result in a controller without calling `evaluate` manually.
+
+Provide a `tokenExtractor` in module options so the middleware knows where to find the BotBye token:
+
+```typescript
+// app.module.ts
+import { Module, NestModule, MiddlewareConsumer } from "@nestjs/common";
+import { BotByeModule, BotByeMiddleware } from "@botbye/nest-express";
+
+@Module({
+  imports: [
+    BotByeModule.register({
+      // Use your project server-key
+      serverKey: "00000000-0000-0000-0000-000000000000",
+      // "x-botbye-token" is an example — pass the token from wherever you store it
+      tokenExtractor: (req) => req.headers["x-botbye-token"] as string | undefined,
+    }),
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // Global: protect all routes
+    consumer.apply(BotByeMiddleware).forRoutes("*");
+  }
+}
+```
+
+Access the result in a controller with `@BotByeResponse()`:
+
+```typescript
+// app.controller.ts
+import { Controller, Post, ForbiddenException } from "@nestjs/common";
+import { BotByeResponse } from "@botbye/nest-express";
+import type { TEvaluationResult } from "@botbye/nest-express";
+
+@Controller()
+export class AppController {
+  @Post("/api/submit")
+  async submit(@BotByeResponse() result: TEvaluationResult) {
+    if (result.decision === "BLOCK") {
+      throw new ForbiddenException();
+    }
+    // proceed normally
+  }
+}
+```
+
+To apply middleware only to specific routes, replace `.forRoutes("*")` with a path or route descriptor:
+
+```typescript
+// Scoped: protect only routes registered under "protected"
+consumer.apply(BotByeMiddleware).forRoutes("protected");
+```
+
+## Documentation
+
+- Web: https://botbye.com/docs/server-side/node-js/nestjs/express
+- Markdown (for AI tools and agents): https://botbye.com/docs/server-side/node-js/nestjs/express.md

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@botbye/nest-express",
+  "version": "2.0.0",
+  "description": "BotBye! integration for NestJS with Express",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://botbye.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/botbye/botbye-nest-express"
+  },
+  "dependencies": {
+    "@botbye/node-core": "^2.0.0",
+    "@botbye/nest-core": "^2.0.0",
+    "@botbye/express": "^2.0.1"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10",
+    "express": ">=4"
+  }
+}

package/src/botbye.module.d.ts

@@ -0,0 +1,6 @@
+import { DynamicModule } from "@nestjs/common";
+import { type TBotByeModuleOptions } from "./botbye.types";
+declare class BotByeModule {
+    static register(options: TBotByeModuleOptions): DynamicModule;
+}
+export { BotByeModule };

package/src/botbye.module.js

@@ -0,0 +1,27 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var BotByeModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotByeModule = void 0;
+const common_1 = require("@nestjs/common");
+const nest_core_1 = require("@botbye/nest-core");
+const express_1 = require("@botbye/express");
+const constants_1 = require("./constants");
+let BotByeModule = BotByeModule_1 = class BotByeModule {
+    static register(options) {
+        return {
+            module: BotByeModule_1,
+            providers: (0, nest_core_1.getProvidersList)(options, (0, express_1.factory)({ module: { name: constants_1.MODULE_NAME, version: constants_1.MODULE_VERSION } })),
+            exports: (0, nest_core_1.getExports)(),
+        };
+    }
+};
+exports.BotByeModule = BotByeModule;
+exports.BotByeModule = BotByeModule = BotByeModule_1 = __decorate([
+    (0, common_1.Module)({})
+], BotByeModule);

package/src/botbye.types.d.ts

@@ -0,0 +1,5 @@
+import type { Request } from "express";
+import type { IBotByeService, TBotByeModuleOptions as TBotByeModuleCoreOptions } from "@botbye/nest-core";
+type TBotByeModuleOptions = TBotByeModuleCoreOptions<Request>;
+type TBotByeService = IBotByeService<Request>;
+export type { TBotByeModuleOptions, TBotByeService };

package/src/botbye.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/constants.d.ts

@@ -0,0 +1,3 @@
+declare const MODULE_NAME = "NESTJS_EXPRESS";
+declare const MODULE_VERSION = "2.0.0";
+export { MODULE_NAME, MODULE_VERSION };

package/src/constants.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_VERSION = exports.MODULE_NAME = void 0;
+const MODULE_NAME = "NESTJS_EXPRESS";
+exports.MODULE_NAME = MODULE_NAME;
+const MODULE_VERSION = "2.0.0";
+exports.MODULE_VERSION = MODULE_VERSION;

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export { BotByeResponse, BotByeMiddleware, BOTBYE_SERVICE_DI_TOKEN } from "@botbye/nest-core";
+export { BotByeModule } from "./botbye.module";
+export type { TBotByeModuleOptions, TBotByeService } from "./botbye.types";
+export type * from "@botbye/nest-core";
+export type * from "@botbye/node-core";

package/src/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotByeModule = exports.BOTBYE_SERVICE_DI_TOKEN = exports.BotByeMiddleware = exports.BotByeResponse = void 0;
+var nest_core_1 = require("@botbye/nest-core");
+Object.defineProperty(exports, "BotByeResponse", { enumerable: true, get: function () { return nest_core_1.BotByeResponse; } });
+Object.defineProperty(exports, "BotByeMiddleware", { enumerable: true, get: function () { return nest_core_1.BotByeMiddleware; } });
+Object.defineProperty(exports, "BOTBYE_SERVICE_DI_TOKEN", { enumerable: true, get: function () { return nest_core_1.BOTBYE_SERVICE_DI_TOKEN; } });
+var botbye_module_1 = require("./botbye.module");
+Object.defineProperty(exports, "BotByeModule", { enumerable: true, get: function () { return botbye_module_1.BotByeModule; } });