Full Toolkit for Next-Level Domain Analysis
Measure how many visitors BotID flags as bots 🤖🧪 (#155)
Felix Wotschofskydd882d88c207
diff --git a/app/api/is-human/route.test.ts b/app/api/is-human/route.test.tsnew file mode 100644index 0000000..3010a16--- /dev/null+++ b/app/api/is-human/route.test.ts@@ -0,0 +1,24 @@+import { describe, expect, it, vi } from 'vitest';++import { POST } from './route';++const { checkBotId } = vi.hoisted(() => ({ checkBotId: vi.fn() }));+vi.mock('botid/server', () => ({ checkBotId }));+vi.mock('@/lib/evlog', () => ({+ useLogger: () => ({ set: vi.fn() }),+ withEvlog: (handler: unknown) => handler,+}));++describe('is-human API', () => {+ it.each([+ ['a human', { isHuman: true, bypassed: false }, true],+ ['a bot', { isHuman: false, bypassed: false }, false],+ ['a bypassed check', { isHuman: true, bypassed: true }, false],+ ])('answers %s with isHuman %s', async (_, verdict, isHuman) => {+ checkBotId.mockResolvedValue(verdict);++ const response = await POST();++ expect(await response.json()).toEqual({ isHuman });+ });+});diff --git a/app/api/is-human/route.ts b/app/api/is-human/route.tsnew file mode 100644index 0000000..d93f0eb--- /dev/null+++ b/app/api/is-human/route.ts@@ -0,0 +1,15 @@+import { checkBotId } from 'botid/server';+import { NextResponse } from 'next/server';++import { useLogger, withEvlog } from '@/lib/evlog';++// BotID's verdict for a visitor (app/providers.tsx). Firewall+// bypass rules and local dev skip BotID but still report a human, so they're+// reported as not human.+export const POST = withEvlog(async () => {+ const log = useLogger();+ const { isHuman, bypassed } = await checkBotId();+ log.set({ isHuman, bypassed });++ return NextResponse.json({ isHuman: isHuman && !bypassed });+});diff --git a/app/providers.test.ts b/app/providers.test.tsnew file mode 100644index 0000000..ad711a7--- /dev/null+++ b/app/providers.test.ts@@ -0,0 +1,33 @@+import { afterEach, describe, expect, it, vi } from 'vitest';++import { reportBotIdVerdict } from './providers';++const respond = (body: string, status = 200) =>+ vi.stubGlobal(+ 'fetch',+ vi.fn(async () => new Response(body, { status })),+ );++describe('BotID trial', () => {+ afterEach(() => vi.unstubAllGlobals());++ it.each([+ ['a human verdict', '{"isHuman":true}', 200, 'human'],+ ['a bot verdict', '{"isHuman":false}', 200, 'bot'],+ // A failed check must not inflate the bot share the trial measures+ ['a server error with a JSON body', '{"message":"failed"}', 500, 'error'],+ ['a non-JSON response', '<html>challenge</html>', 403, 'error'],+ ])('reports %s as %s', async (_, body, status, result) => {+ respond(body, status);+ const reportEvent = vi.fn();++ await reportBotIdVerdict(reportEvent);++ // Non-interactive, so the event doesn't turn bounces into engaged visits+ expect(reportEvent).toHaveBeenCalledWith(+ 'BotID: Check',+ { result },+ { interactive: false },+ );+ });+});diff --git a/app/providers.tsx b/app/providers.tsxindex 53fd2be..6c64fd9 100644--- a/app/providers.tsx+++ b/app/providers.tsx@@ -3,10 +3,38 @@import { EvlogProvider } from 'evlog/next/client';import PlausibleProvider from 'next-plausible';import { ThemeProvider } from 'next-themes';-import { type ComponentProps, type FC, type ReactNode } from 'react';+import { type ComponentProps, type FC, type ReactNode, useEffect } from 'react';import { SWRConfig } from 'swr';import { env } from '@/env';+import { useAnalytics } from '@/lib/analytics';++// Trial: reports BotID's verdict for every visitor as a Plausible event, so the+// share of visitors it would drop from analytics can be measured before+// analytics are gated on it.+export const reportBotIdVerdict = (+ reportEvent: ReturnType<typeof useAnalytics>['reportEvent'],+) =>+ fetch('/api/is-human', { method: 'POST' })+ .then((response) => {+ // A failed check is an error, never a bot verdict+ if (!response.ok) throw new Error(`HTTP ${response.status}`);+ return response.json();+ })+ .then((body): 'human' | 'bot' => (body.isHuman === true ? 'human' : 'bot'))+ .catch(() => 'error' as const)+ .then((result) =>+ // Non-interactive, so single-page visits still count as bounces+ reportEvent('BotID: Check', { result }, { interactive: false }),+ );++const useBotIdTrial = () => {+ const { reportEvent } = useAnalytics();++ useEffect(() => {+ reportBotIdVerdict(reportEvent);+ }, [reportEvent]);+};type CustomizedPlausibleProviderProps = {children: ReactNode;@@ -46,16 +74,20 @@ type ProvidersProps = {children: ReactNode;};-export const Providers: FC<ProvidersProps> = ({ children }) => (- <EvlogProvider- service="domain-digger"- // Using the non-default endpoint since default _evlog is considered hidden by Next.js- transport={{ enabled: true, endpoint: '/api/evlog/ingest' }}- >- <ThemeProvider attribute="class">- <SWRConfig value={{ fetcher: swrFetcher }}>- <CustomizedPlausibleProvider>{children}</CustomizedPlausibleProvider>- </SWRConfig>- </ThemeProvider>- </EvlogProvider>-);+export const Providers: FC<ProvidersProps> = ({ children }) => {+ useBotIdTrial();++ return (+ <EvlogProvider+ service="domain-digger"+ // Using the non-default endpoint since default _evlog is considered hidden by Next.js+ transport={{ enabled: true, endpoint: '/api/evlog/ingest' }}+ >+ <ThemeProvider attribute="class">+ <SWRConfig value={{ fetcher: swrFetcher }}>+ <CustomizedPlausibleProvider>{children}</CustomizedPlausibleProvider>+ </SWRConfig>+ </ThemeProvider>+ </EvlogProvider>+ );+};diff --git a/instrumentation-client.ts b/instrumentation-client.tsnew file mode 100644index 0000000..4db93e1--- /dev/null+++ b/instrumentation-client.ts@@ -0,0 +1,11 @@+import { initBotId } from 'botid/client/core';++initBotId({ protect: [{ path: '/api/is-human', method: 'POST' }] });++// Queue Plausible events reported before its script loads (such as the BotID+// check in app/providers.tsx); the script replays them once loaded.+const queue: unknown[][] = [];+(window as { plausible?: unknown }).plausible ??= Object.assign(+ (...args: unknown[]) => queue.push(args),+ { q: queue },+);diff --git a/lib/analytics.test.ts b/lib/analytics.test.tsnew file mode 100644index 0000000..5c52898--- /dev/null+++ b/lib/analytics.test.ts@@ -0,0 +1,23 @@+import { describe, expect, it, vi } from 'vitest';++import { useAnalytics } from './analytics';++const { plausible } = vi.hoisted(() => ({ plausible: vi.fn() }));+vi.mock('next-plausible', () => ({ usePlausible: () => plausible }));+vi.mock('evlog/next/client', () => ({ log: { info: vi.fn() } }));+vi.mock('react', () => ({ useCallback: (callback: unknown) => callback }));++describe('reportEvent', () => {+ it('passes interactive: false through to Plausible', () => {+ useAnalytics().reportEvent(+ 'BotID: Check',+ { result: 'bot' },+ { interactive: false },+ );++ expect(plausible).toHaveBeenCalledWith('BotID: Check', {+ props: { result: 'bot' },+ interactive: false,+ });+ });+});diff --git a/lib/analytics.ts b/lib/analytics.tsindex 70da3cc..cf35993 100644--- a/lib/analytics.ts+++ b/lib/analytics.ts@@ -5,6 +5,7 @@ import { useCallback } from 'react';type EmptyEvent = Record<string, never>;type Events = {+ 'BotID: Check': { result: 'human' | 'bot' | 'error' };'Carbon Ad: Blocked': { reason: 'script' | 'no-ad' };'Carbon Ad: Show': EmptyEvent;'Copy Button: Click': { value: string };@@ -26,9 +27,14 @@ export const useAnalytics = () => {// Stable so it can sit in effect dependenciesconst reportEvent = useCallback(- <T extends keyof Events>(event: T, props: Events[T]) => {+ <T extends keyof Events>(+ event: T,+ props: Events[T],+ // interactive: false keeps an event from counting against bounce rate+ options?: { interactive?: boolean },+ ) => {log.info({ message: 'analytics_event', event, props });- plausible(event, { props });+ plausible(event, { props, ...options });},[plausible],);diff --git a/package.json b/package.jsonindex a7831f2..553ea19 100644--- a/package.json+++ b/package.json@@ -32,6 +32,7 @@"@uidotdev/usehooks": "^2.4.1","@vercel/analytics": "^2.0.1","@vercel/speed-insights": "^2.0.0",+ "botid": "^1.5.12","class-variance-authority": "^0.7.1","clsx": "^2.1.1","dataloader": "^2.2.3",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 43ea61e..104efea 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -60,6 +60,9 @@ importers:'@vercel/speed-insights':specifier: ^2.0.0version: 2.0.0([email protected](@babel/[email protected])(@types/[email protected])([email protected])([email protected]([email protected]))([email protected]))([email protected])+ botid:+ specifier: ^1.5.12+ version: 1.5.12([email protected](@babel/[email protected])(@types/[email protected])([email protected])([email protected]([email protected]))([email protected]))([email protected])class-variance-authority:specifier: ^0.7.1version: 0.7.1@@ -2532,6 +2535,17 @@ packages:resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}+ resolution: {integrity: sha512-bUYGLDLbNOQJyTVfuBGzm1ADztJ/euV6XH9JgXZ9MG2CZvElgOycybVOsgHBjVwB4tFl77g7zs31kEvjYm2gAw==}+ peerDependencies:+ next: '*'+ react: ^18.0.0 || ^19.0.0+ peerDependenciesMeta:+ next:+ optional: true+ react:+ optional: true+resolution: {integrity: sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==}@@ -6829,6 +6843,11 @@ snapshots:+ [email protected]([email protected](@babel/[email protected])(@types/[email protected])([email protected])([email protected]([email protected]))([email protected]))([email protected]):+ optionalDependencies:+ next: 16.4.3(@babel/[email protected])(@types/[email protected])([email protected])([email protected]([email protected]))([email protected])+ react: 19.3.1+dependencies:balanced-match: 1.0.2