This file describes how to integrate protection service [BotBye!](https://botbye.com) using Nuxt # Nuxt BotBye! integration for [Nuxt]( https://nuxt.com/ ) applications. ## Install ```bash npm i @botbye/nuxt ``` ```bash yarn add @botbye/nuxt ``` Requires `nuxt >= 3` as a peer dependency. ## Package exports The package exposes three entry points: - `@botbye/nuxt/server` — server-side SDK: `init`, `evaluate`, `dev`, `factory` - `@botbye/nuxt/client` — client-side utilities: `initChallenges`, `runChallenge`, `setUserId` - `@botbye/nuxt/module` — Nuxt module for automatic client-side initialization ## Client-side Configuration The `@botbye/nuxt/client` entry point provides utilities for initializing the BotBye client-side SDK and running challenge flows in the browser. ### Using the Nuxt module (recommended) Add the module to `nuxt.config.ts` to enable automatic client initialization and TypeScript support for `useRuntimeConfig().public.botbye`: ```typescript // nuxt.config.ts export default defineNuxtConfig({ modules: ["@botbye/nuxt/module"], botbyeModule: { inject: true, }, runtimeConfig: { public: { botbye: { // Use your client key clientKey: "00000000-0000-0000-0000-000000000000", }, }, }, }); ``` When `inject: true`, the module registers a client plugin that calls `initChallenges` automatically using `runtimeConfig.public.botbye`. ### Manual initialization If you prefer not to use `inject: true`, call `initChallenges` directly in a client-side Nuxt plugin: ```typescript // plugins/botbye.client.ts import { initChallenges } from "@botbye/nuxt/client"; export default defineNuxtPlugin(() => { initChallenges({ // Use your client key clientKey: "00000000-0000-0000-0000-000000000000", }); }); ``` ## Client-side Usage Once the SDK is initialized, call `runChallenge()` anywhere in client-side code to acquire a token and pass it to your API: ```typescript import { runChallenge } from "@botbye/nuxt/client"; const onLoginClick = async () => { const token = await runChallenge(); await $fetch("/api/login", { method: "POST", headers: { // "x-botbye-token" is an example — pass the token from wherever you store it "x-botbye-token": token, }, body: { email, password }, }); }; ``` ## User identification Call `setUserId` after a successful authentication to associate the current session with a user. This helps BotBye detect multi-account abuse. ```typescript import { setUserId } from "@botbye/nuxt/client"; const response = await login({ username, password }); if (response.userId) { setUserId(response.userId); } ``` ## Server-side Configuration Call `init` once at server startup with your server key. The recommended place in Nuxt is a Nitro server plugin: ```typescript // server/plugins/botbye.ts import { init } from "@botbye/nuxt/server"; export default defineNitroPlugin(() => { init({ // Use your project server-key serverKey: "00000000-0000-0000-0000-000000000000", }); }); ``` ### `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 | ## Server-side Usage Call `evaluate` in API handlers or server middleware where bot protection is needed. It accepts an event object describing what you know about the request and the context around it, and returns a promise that resolves to a decision. ```javascript import { evaluate } from "@botbye/nuxt/server"; export default defineEventHandler(async (event) => { const result = await evaluate({ type: "validate", request: { request: event, // "x-botbye-token" is an example — pass the token from wherever you store it token: getRequestHeader(event, "x-botbye-token"), }, }); if (result.decision === "BLOCK") { throw createError({ statusCode: 403, message: "Forbidden" }); } // 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 outermost layer — server middleware or API handler — 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 H3Event object directly — SDK extracts everything automatically | { request: H3Event; token?: string | null } // Option B: construct request info manually | { ip: string; headers: Record; requestMethod?: string | null; requestUri?: string | null; token?: string | null }; customFields?: Record; } ``` The SDK extracts IP, headers, method, and URI from the `H3Event` object 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 that contains information about the user's device. Pass whatever the client sent; if no token is received, the decision will be `"BLOCK"`. ```javascript import { evaluate } from "@botbye/nuxt/server"; export default defineEventHandler(async (event) => { const result = await evaluate({ type: "validate", request: { request: event, // "x-botbye-token" is an example — pass the token from wherever you store it token: getRequestHeader(event, "x-botbye-token"), }, }); if (result.decision === "BLOCK") { throw createError({ statusCode: 403, message: "Forbidden" }); } // proceed normally }); ``` --- ### `risk` — domain-level risk scoring Use inside API handlers that already know the user: auth, payments, account management, etc. 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; requestMethod?: string | null; requestUri?: string | null; token?: string | null } // H3Event also accepted if convenient | { request: H3Event }; 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; botbyeResult?: string; // if a validate call was made earlier, pass its result.botbyeResult here to link the requests; omit if there was no prior validate } ``` `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 H3Event object if that's more convenient. ```javascript import { evaluate } from "@botbye/nuxt/server"; // Inside an API handler, after a login attempt async function onLoginAttempt({ ip, userId, email, loginSucceeded }) { const result = await evaluate({ type: "risk", request: { ip, }, event: { type: "login", status: loginSucceeded ? "SUCCESSFUL" : "FAILED", }, user: { accountId: userId, email, }, }); if (result.decision === "BLOCK") { // Lock account, trigger MFA, send alert, etc. } } ``` #### Linking `validate` and `risk` events When the same request is evaluated at two layers — for example, once at the edge in server middleware (`type: "validate"`) and then again inside an API handler (`type: "risk"`) — BotBye can link both events and display them as a single event in the dashboard. **Step 1 — server middleware** (edge layer): run `validate` and capture `botbye_result`: ```javascript // server/middleware/botbye.js export default defineEventHandler(async (event) => { const edgeResult = await evaluate({ type: "validate", request: { request: event, // "x-botbye-token" is an example — pass the token from wherever you store it token: getRequestHeader(event, "x-botbye-token"), }, }); const edgeBotbyeResult = edgeResult.botbye_result; // Pass edgeBotbyeResult downstream — event context, shared state, a forwarded header, etc. }); ``` **Step 2 — API handler** (domain layer): pass it as `botbyeResult` in the `risk` call: ```javascript // server/api/auth/login.post.js const riskResult = await evaluate({ type: "risk", request: { ip }, event: { type: "login", status: loginSucceeded ? "SUCCESSFUL" : "FAILED", }, user: { accountId: userId, email, }, botbyeResult: edgeBotbyeResult, }); ``` `botbye_result` is optional in the response — if it is absent, omit `botbyeResult` and the events will be recorded independently. --- ### `full` — edge check and domain scoring in one call Use when you have all context at once: raw request, token, user, and event. A login API handler is a typical example — it receives the request and immediately knows the user and outcome. **Event fields:** ```typescript { type: "full"; request: | { request: H3Event; token?: string | null } | { ip: string; headers: Record; 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; } ``` Equivalent to running `validate` and `risk` in a single call. ```javascript import { evaluate } from "@botbye/nuxt/server"; // server/api/auth/login.post.js export default defineEventHandler(async (event) => { const { email, password } = await readBody(event); const user = await findUser(email); const loginSucceeded = user && (await checkPassword(user, password)); const result = await evaluate({ type: "full", request: { request: event, // "x-botbye-token" is an example — pass the token from wherever you store it token: getRequestHeader(event, "x-botbye-token"), }, event: { type: "login", status: loginSucceeded ? "SUCCESSFUL" : "FAILED", }, user: { accountId: user?.id ?? "unknown", email, }, }); if (result.decision === "BLOCK") { throw createError({ statusCode: 403, message: "Forbidden" }); } // proceed normally }); ``` ## Response `evaluate` always returns a `Promise`: ```typescript type TEvaluationResult = | { decision: "ALLOW" | "BLOCK" | "CHALLENGE"; request_id: string; risk_score: number; scores: Record; signals: string[]; botbye_result?: string; } | { decision: "ALLOW"; botbye_result?: string; 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. ## Examples of BotBye API responses Blocked (bot detected): ```javascript { "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583", "decision": "BLOCK", "risk_score": 0.95, "scores": { "bot": 0.95 }, "signals": ["AutomationTool"] } ``` Allowed: ```javascript { "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583", "decision": "ALLOW", "risk_score": 0.05, "scores": { "bot": 0.05, "ato": 0.02 }, "signals": [] } ``` Challenge: ```javascript { "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583", "decision": "CHALLENGE", "risk_score": 0.65, "scores": { "bot": 0.65 }, "signals": ["SuspiciousFingerprint"], "challenge": { "type": "captcha", "token": "..." } } ``` Invalid `server-key`: ```javascript { "decision": "ALLOW", "error": { "message": "[BotBye] Bad Request: Invalid Server Key" } } ``` ## Middleware usage Nitro server middleware (`server/middleware/`) runs before every matched request and is the best place to apply edge-level bot protection globally: ```javascript // server/middleware/botbye.js import { evaluate } from "@botbye/nuxt/server"; export default defineEventHandler(async (event) => { const result = await evaluate({ type: "validate", request: { request: event, // "x-botbye-token" is an example — pass the token from wherever you store it token: getRequestHeader(event, "x-botbye-token"), }, }); if (result.decision === "BLOCK") { throw createError({ statusCode: 403, message: "Forbidden" }); } }); ``` ## Advanced: multiple instances Use `factory` to create independent SDK instances (useful when protecting multiple projects from one service): ```javascript import { factory } from "@botbye/nuxt/server"; const sdk = factory(); sdk.init({ // Use your project server-key serverKey: "00000000-0000-0000-0000-000000000000", }); const result = await sdk.evaluate({ type: "validate", request: { request: event, token }, }); ``` ## Dev utilities ```javascript import { dev } from "@botbye/nuxt/server"; dev.setLoggerLevel("debug"); // "error" | "warn" | "info" | "debug" | "log" ``` There is a prompt for an LLM model that describes how to integrate BotBye! protection into a project: ```plaintext On client side: Integrate BotBye client-side bot protection into a Nuxt project using the @botbye/nuxt package. 1. Install the package: npm i @botbye/nuxt or yarn add @botbye/nuxt 2. Add the module to nuxt.config.ts and pass your clientKey via runtimeConfig: modules: ["@botbye/nuxt/module"], botbyeModule: { inject: true }, runtimeConfig: { public: { botbye: { clientKey: "00000000-0000-0000-0000-000000000000" } } } The module automatically reads the public clientKey and initializes the challenge runner. 3. In any component or composable, generate a token before a protected request: import { runChallenge } from "@botbye/nuxt/client" const token = await runChallenge() Call runChallenge() immediately before the API call — do not cache the result. 4. Send the token to your Nuxt server route in the x-botbye-token header: await $fetch("/api/login", { method: "POST", headers: { "x-botbye-token": token } }) 5. On the server side (Nitro), validate the token using evaluate (see server-side setup). Full integration guide: https://botbye.com/docs/server-side/node-js/nuxt.md When the integration is complete, ask me for the clientKey and replace the placeholder in the appropriate places. When the integration is complete, ask for the keys and replace the placeholder in the appropriate places. On server side: Integrate BotBye server-side bot protection into a Nuxt application using the @botbye/nuxt package. 1. Install the package: npm i @botbye/nuxt or yarn add @botbye/nuxt 2. Create a Nitro plugin at server/plugins/botbye.ts that initializes BotBye with your server-key: import { init } from "@botbye/nuxt/server" export default defineNitroPlugin(() => { init({ serverKey: "00000000-0000-0000-0000-000000000000" }) }) 3. Call evaluate in API handlers or server middleware. Three event types: import { evaluate } from "@botbye/nuxt/server" const result = await evaluate({ type: "validate", request: { request: event, token: getRequestHeader(event, "x-botbye-token") } }) if (result.decision === "BLOCK") throw createError({ statusCode: 403, message: "Forbidden" }) 4. There are three event types — choose based on available context: - "validate" — edge-level bot check (request + token only) - "risk" — domain-level risk scoring (add event: { type, status } and user: { accountId, ... }) - "full" — both in one call (request, token, event, and user) result.decision is "ALLOW", "CHALLENGE", or "BLOCK". Full integration guide: https://botbye.com/docs/server-side/node-js/nuxt.md When the integration is complete, ask for the keys and replace the placeholder in the appropriate places.```