@walkeros/server-transformer-bot 4.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @walkeros/server-transformer-bot
+
+Server-side bot and AI-agent detection transformer for walkerOS.
+
+Annotates events with `user.botScore` (0-99, higher = more bot), `user.agentScore` (0-99, higher = more AI agent), and optionally `user.agentProduct` (matched UA substring). Never drops events — downstream destination mappings decide policy.
+
+## Install
+
+```bash
+npm install @walkeros/server-transformer-bot
+```
+
+## Quick start
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { transformerBot } from '@walkeros/server-transformer-bot';
+
+await startFlow({
+  sources: {
+    express: {
+      package: '@walkeros/server-source-express',
+      config: {
+        ingest: {
+          userAgent: 'req.headers.user-agent',
+        },
+      },
+    },
+  },
+  transformers: {
+    bot: { code: transformerBot },
+  },
+  destinations: {
+    ga4: {
+      package: '@walkeros/server-destination-google-ga4',
+      before: 'bot',
+      // mapping can filter: if (event.user.botScore > 50) drop
+    },
+  },
+});
+```
+
+After the transformer runs:
+
+```json
+{
+  "user": {
+    "botScore": 0,
+    "agentScore": 0
+  }
+}
+```
+
+## What it detects (v1)
+
+| Visitor | botScore | agentScore | agentProduct |
+|---|---|---|---|
+| Real browser (Chrome, Firefox, Safari, Edge) | 0 | 0 | — |
+| Empty / missing User-Agent | 70 | 0 | — |
+| curl / wget / python-requests / well-known crawlers | 80 | 0 | — |
+| AI training crawlers (GPTBot, ClaudeBot, CCBot, Bytespider, etc.) | 95 | 95 | e.g. "GPTBot" |
+| AI search-index crawlers (OAI-SearchBot, Claude-SearchBot, PerplexityBot) | 95 | 95 | e.g. "PerplexityBot" |
+| AI user-action agents (ChatGPT-User, Claude-User, Perplexity-User, etc.) | 90 | 95 | e.g. "ChatGPT-User" |
+
+## Output paths
+
+All three outputs are configurable via `settings.output`:
+
+| Field | Default path | Notes |
+|---|---|---|
+| `botScore` | `user.botScore` | Set to `"ingest.bot.score"` to route to pipeline scratch instead of the event. Set to `""` to skip writing. |
+| `agentScore` | `user.agentScore` | v1 emits 0 or 95 only. |
+| `agentProduct` | (off) | Set to `"user.agentProduct"` or similar to enable. |
+
+## Destination filtering recipes
+
+Drop all bots:
+
+```
+event.user.botScore > 50
+```
+
+Drop crawlers but keep user-action AI traffic:
+
+```
+event.user.botScore > 50 AND event.user.agentProduct NOT LIKE '%-User'
+```
+
+AI traffic report:
+
+```
+event.user.agentScore > 50, grouped by event.user.agentProduct
+```
+
+## Not in v1 (planned for v1.1+)
+
+These signals are deferred. The `settings.input` schema reserves the relevant input field names so adding them in v1.1 will not be a breaking change.
+
+- **Header consistency heuristics** — `Sec-Fetch-*` missing on Chromium UAs, `Sec-CH-UA` major version mismatch with UA, missing `Accept-Language`. Requires a structured-headers parser, GREASE filtering, and a captured-headers fixture suite to avoid false positives on WebView, Tor, corporate proxies, and old Safari.
+- **ASN / datacenter-IP detection** — bring-your-own lookup function (the package will stay dependency-free; MaxMind GeoLite ASN's CC-BY-SA license precludes embedding).
+- **Reverse DNS verification** for true `verified-bot` status (e.g. confirming Googlebot is actually Google).
+- **Web-side runtime checks** — `navigator.webdriver`, `userAgentData` from a browser source.
+- **Behavioral signals** (rate, session shape) — needs a store.
+- **TLS / JA4 fingerprinting** — not application-layer reachable; would consume an upstream-injected `ja4` header if provided.
+- **agentScore graduation** — v1 emits 0 or 95. v1.1 will use intermediate values (e.g. 70 for unverified UA claim, 99 for IP-reverse-DNS verified).
+
+## Limits
+
+Will not catch: residential-proxy + stealth-patched Chrome + realistic behavior; paid CAPTCHA-solver farms (2Captcha residential, etc.); real-browser-as-a-service providers (Bright Data, ScrapingBee, Browserbase, Hyperbrowser, Browserless). For that threat model use Cloudflare Bot Management, DataDome, or HUMAN.
+
+## License
+
+MIT

package/dist/dev.d.mts

@@ -0,0 +1,107 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Flow, Hint } from '@walkeros/core';
+
+declare const SettingsSchema: z.ZodObject<{
+    input: z.ZodOptional<z.ZodObject<{
+        userAgent: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        ip: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        acceptLanguage: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        acceptEncoding: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchSite: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchMode: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchDest: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchUser: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secChUa: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secChUaMobile: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secChUaPlatform: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>>;
+    output: z.ZodOptional<z.ZodObject<{
+        botScore: z.ZodOptional<z.ZodString>;
+        agentScore: z.ZodOptional<z.ZodString>;
+        agentProduct: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_settings as settings };
+}
+
+/** Real Chrome — botScore 0, agentScore 0. */
+declare const humanChrome: Flow.StepExample;
+/** GPTBot — training crawler. */
+declare const gptBotCrawler: Flow.StepExample;
+/** ChatGPT-User — user-action AI agent. */
+declare const chatgptUserAgent: Flow.StepExample;
+/** curl — caught by isbot. */
+declare const curlClient: Flow.StepExample;
+/** Empty / missing UA — score 70 (suspicious; real browsers rarely strip UA). */
+declare const missingUA: Flow.StepExample;
+
+declare const step_chatgptUserAgent: typeof chatgptUserAgent;
+declare const step_curlClient: typeof curlClient;
+declare const step_gptBotCrawler: typeof gptBotCrawler;
+declare const step_humanChrome: typeof humanChrome;
+declare const step_missingUA: typeof missingUA;
+declare namespace step {
+  export { step_chatgptUserAgent as chatgptUserAgent, step_curlClient as curlClient, step_gptBotCrawler as gptBotCrawler, step_humanChrome as humanChrome, step_missingUA as missingUA };
+}
+
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_step as step };
+}
+
+declare const hints: Hint.Hints;
+
+export { index as examples, hints, index$1 as schemas };

package/dist/dev.d.ts

@@ -0,0 +1,107 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Flow, Hint } from '@walkeros/core';
+
+declare const SettingsSchema: z.ZodObject<{
+    input: z.ZodOptional<z.ZodObject<{
+        userAgent: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        ip: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        acceptLanguage: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        acceptEncoding: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchSite: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchMode: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchDest: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secFetchUser: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secChUa: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secChUaMobile: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        secChUaPlatform: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodUnknown>;
+            fn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>>;
+    output: z.ZodOptional<z.ZodObject<{
+        botScore: z.ZodOptional<z.ZodString>;
+        agentScore: z.ZodOptional<z.ZodString>;
+        agentProduct: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_settings as settings };
+}
+
+/** Real Chrome — botScore 0, agentScore 0. */
+declare const humanChrome: Flow.StepExample;
+/** GPTBot — training crawler. */
+declare const gptBotCrawler: Flow.StepExample;
+/** ChatGPT-User — user-action AI agent. */
+declare const chatgptUserAgent: Flow.StepExample;
+/** curl — caught by isbot. */
+declare const curlClient: Flow.StepExample;
+/** Empty / missing UA — score 70 (suspicious; real browsers rarely strip UA). */
+declare const missingUA: Flow.StepExample;
+
+declare const step_chatgptUserAgent: typeof chatgptUserAgent;
+declare const step_curlClient: typeof curlClient;
+declare const step_gptBotCrawler: typeof gptBotCrawler;
+declare const step_humanChrome: typeof humanChrome;
+declare const step_missingUA: typeof missingUA;
+declare namespace step {
+  export { step_chatgptUserAgent as chatgptUserAgent, step_curlClient as curlClient, step_gptBotCrawler as gptBotCrawler, step_humanChrome as humanChrome, step_missingUA as missingUA };
+}
+
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_step as step };
+}
+
+declare const hints: Hint.Hints;
+
+export { index as examples, hints, index$1 as schemas };

package/dist/dev.js

@@ -0,0 +1 @@
+"use strict";var e,t=Object.defineProperty,r=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,n=Object.prototype.hasOwnProperty,i=(e,r)=>{for(var o in r)t(e,o,{get:r[o],enumerable:!0})},a={};i(a,{examples:()=>d,hints:()=>w,schemas:()=>s}),module.exports=(e=a,((e,i,a,s)=>{if(i&&"object"==typeof i||"function"==typeof i)for(let c of o(i))n.call(e,c)||c===a||t(e,c,{get:()=>i[c],enumerable:!(s=r(i,c))||s.enumerable});return e})(t({},"__esModule",{value:!0}),e));var s={};i(s,{SettingsSchema:()=>p,settings:()=>u});var c=require("@walkeros/core/dev"),l=require("@walkeros/core/dev"),g=l.z.union([l.z.string().describe('Dot-notation path like "ingest.userAgent"'),l.z.object({key:l.z.string().optional(),value:l.z.unknown().optional(),fn:l.z.string().optional()}).describe("Mapping value object")]),p=l.z.object({input:l.z.object({userAgent:g.optional(),ip:g.optional(),acceptLanguage:g.optional(),acceptEncoding:g.optional(),secFetchSite:g.optional(),secFetchMode:g.optional(),secFetchDest:g.optional(),secFetchUser:g.optional(),secChUa:g.optional(),secChUaMobile:g.optional(),secChUaPlatform:g.optional()}).optional().describe("Input signal sources, resolved via getMappingValue against { event, ingest }. v1 only reads userAgent; other fields reserved for v1.1 header heuristics."),output:l.z.object({botScore:l.z.string().optional().describe('Path for bot score (0-99, higher = more bot). Default: "user.botScore". Use "ingest.*" to route to pipeline scratch instead of the event. Empty string or omit = skip.'),agentScore:l.z.string().optional().describe('Path for AI agent score (0-99). v1 emits 0 (no match) or 95 (UA-map match). Default: "user.agentScore".'),agentProduct:l.z.string().optional().describe('Path for matched UA substring (e.g. "ChatGPT-User"). Off by default — set to enable.')}).optional().describe("Output paths for bot/agent annotations.")}).describe("Bot detection transformer: annotates events with bot and AI-agent scores."),u=(0,c.zodToSchema)(p),d={};i(d,{step:()=>h});var h={};i(h,{chatgptUserAgent:()=>f,curlClient:()=>A,gptBotCrawler:()=>v,humanChrome:()=>m,missingUA:()=>S});var b={name:"page view",data:{title:"Home",id:"/"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}},m={title:"Human visitor (Chrome)",description:"Modern Chrome UA. No bot or agent signals.",in:{...b},out:[["return",{event:{...b,user:{botScore:0,agentScore:0}}}]]},v={title:"GPTBot training crawler",description:"OpenAI training crawler. Both botScore and agentScore are high.",in:{...b,id:"ev-1700000601"},out:[["return",{event:{...b,id:"ev-1700000601",user:{botScore:95,agentScore:95}}}]]},f={title:"ChatGPT-User (user-action AI)",description:"A real human routed an AI to fetch this page. botScore high but lower than crawlers — agentProduct lets destinations keep this traffic.",in:{...b,id:"ev-1700000602"},out:[["return",{event:{...b,id:"ev-1700000602",user:{botScore:90,agentScore:95}}}]]},A={public:!1,description:"curl client — caught by isbot. agentScore zero.",in:{...b,id:"ev-1700000603"},out:[["return",{event:{...b,id:"ev-1700000603",user:{botScore:80,agentScore:0}}}]]},S={public:!1,description:"No User-Agent — baseline 70 (UA stripping is overwhelmingly bots or hardened privacy tools).",in:{...b,id:"ev-1700000604"},out:[["return",{event:{...b,id:"ev-1700000604",user:{botScore:70,agentScore:0}}}]]},w={"ingest-prerequisite":{text:'The bot transformer reads userAgent from ctx.ingest (path "ingest.userAgent" by default). The upstream server source must populate it via config.ingest mapping, otherwise the UA is empty and every event scores 70 (baseline for missing UA).',code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",config:{ingest:{userAgent:"req.headers.user-agent"}}}},transformers:{bot:{package:"@walkeros/server-transformer-bot"}}},null,2)}]},"output-routing":{text:"Outputs default to event.user.botScore and event.user.agentScore. Redirect to ingest.* to keep the analytics event clean while still routing on the score downstream. Empty string (or omit) skips writing that field entirely. agentProduct is off by default — set it to enable writing the matched UA substring.",code:[{lang:"json",code:JSON.stringify({transformers:{bot:{package:"@walkeros/server-transformer-bot",config:{settings:{output:{botScore:"ingest.bot.score",agentScore:"ingest.bot.agent",agentProduct:"user.agentProduct"}}}}}},null,2)}]},"destination-filtering":{text:'Recommended destination-mapping recipes. Drop all bots: botScore > 50. Drop crawlers but keep user-action AI traffic: botScore > 50 AND agentProduct NOT LIKE "%-User". AI traffic report: group by agentProduct WHERE agentScore > 50. The transformer never drops events — filtering is always a destination decision.'},"detection-scope":{text:"v1 is UA-only: wraps isbot (curl, wget, headless Chrome defaults, well-known crawlers) plus a curated AI-agent UA map (OpenAI, Anthropic, Perplexity, Mistral, Meta, Google, Apple, Amazon, DuckDuckGo, ByteDance, Common Crawl). It will NOT catch: residential-proxy + stealth Chrome + realistic behavior; reverse-DNS-verified search engines; client-side runtime tells. v1.1 adds header consistency heuristics (Sec-Fetch, Sec-CH-UA, Accept-Language) with proper GREASE handling. For commercial-grade detection use Cloudflare Bot Management, DataDome, or HUMAN."}};//# sourceMappingURL=dev.js.map

package/dist/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/dev.ts","../src/schemas/index.ts","../src/schemas/settings.ts","../src/examples/index.ts","../src/examples/step.ts","../src/hints.ts"],"sourcesContent":["export * as schemas from './schemas';\nexport * as examples from './examples';\nexport { hints } from './hints';\n","import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport const settings = zodToSchema(SettingsSchema);\n","import { z } from '@walkeros/core/dev';\n\nconst MappingValueSchema = z.union([\n  z.string().describe('Dot-notation path like \"ingest.userAgent\"'),\n  z\n    .object({\n      key: z.string().optional(),\n      value: z.unknown().optional(),\n      fn: z.string().optional(),\n    })\n    .describe('Mapping value object'),\n]);\n\nexport const SettingsSchema = z\n  .object({\n    input: z\n      .object({\n        userAgent: MappingValueSchema.optional(),\n        ip: MappingValueSchema.optional(),\n        acceptLanguage: MappingValueSchema.optional(),\n        acceptEncoding: MappingValueSchema.optional(),\n        secFetchSite: MappingValueSchema.optional(),\n        secFetchMode: MappingValueSchema.optional(),\n        secFetchDest: MappingValueSchema.optional(),\n        secFetchUser: MappingValueSchema.optional(),\n        secChUa: MappingValueSchema.optional(),\n        secChUaMobile: MappingValueSchema.optional(),\n        secChUaPlatform: MappingValueSchema.optional(),\n      })\n      .optional()\n      .describe(\n        'Input signal sources, resolved via getMappingValue against { event, ingest }. v1 only reads userAgent; other fields reserved for v1.1 header heuristics.',\n      ),\n    output: z\n      .object({\n        botScore: z\n          .string()\n          .optional()\n          .describe(\n            'Path for bot score (0-99, higher = more bot). Default: \"user.botScore\". Use \"ingest.*\" to route to pipeline scratch instead of the event. Empty string or omit = skip.',\n          ),\n        agentScore: z\n          .string()\n          .optional()\n          .describe(\n            'Path for AI agent score (0-99). v1 emits 0 (no match) or 95 (UA-map match). Default: \"user.agentScore\".',\n          ),\n        agentProduct: z\n          .string()\n          .optional()\n          .describe(\n            'Path for matched UA substring (e.g. \"ChatGPT-User\"). Off by default — set to enable.',\n          ),\n      })\n      .optional()\n      .describe('Output paths for bot/agent annotations.'),\n  })\n  .describe(\n    'Bot detection transformer: annotates events with bot and AI-agent scores.',\n  );\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","export * as step from './step';\n","import type { Flow } from '@walkeros/core';\n\nconst baseEvent = {\n  name: 'page view',\n  data: { title: 'Home', id: '/' },\n  id: 'ev-1700000600',\n  trigger: 'load',\n  entity: 'page',\n  action: 'view',\n  timestamp: 1700000600,\n  source: { type: 'express', platform: 'server' as const },\n};\n\n/** Real Chrome — botScore 0, agentScore 0. */\nexport const humanChrome: Flow.StepExample = {\n  title: 'Human visitor (Chrome)',\n  description: 'Modern Chrome UA. No bot or agent signals.',\n  in: { ...baseEvent },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          user: { botScore: 0, agentScore: 0 },\n        },\n      },\n    ],\n  ],\n};\n\n/** GPTBot — training crawler. */\nexport const gptBotCrawler: Flow.StepExample = {\n  title: 'GPTBot training crawler',\n  description:\n    'OpenAI training crawler. Both botScore and agentScore are high.',\n  in: { ...baseEvent, id: 'ev-1700000601' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000601',\n          user: { botScore: 95, agentScore: 95 },\n        },\n      },\n    ],\n  ],\n};\n\n/** ChatGPT-User — user-action AI agent. */\nexport const chatgptUserAgent: Flow.StepExample = {\n  title: 'ChatGPT-User (user-action AI)',\n  description:\n    'A real human routed an AI to fetch this page. botScore high but lower than crawlers — agentProduct lets destinations keep this traffic.',\n  in: { ...baseEvent, id: 'ev-1700000602' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000602',\n          user: { botScore: 90, agentScore: 95 },\n        },\n      },\n    ],\n  ],\n};\n\n/** curl — caught by isbot. */\nexport const curlClient: Flow.StepExample = {\n  public: false,\n  description: 'curl client — caught by isbot. agentScore zero.',\n  in: { ...baseEvent, id: 'ev-1700000603' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000603',\n          user: { botScore: 80, agentScore: 0 },\n        },\n      },\n    ],\n  ],\n};\n\n/** Empty / missing UA — score 70 (suspicious; real browsers rarely strip UA). */\nexport const missingUA: Flow.StepExample = {\n  public: false,\n  description:\n    'No User-Agent — baseline 70 (UA stripping is overwhelmingly bots or hardened privacy tools).',\n  in: { ...baseEvent, id: 'ev-1700000604' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000604',\n          user: { botScore: 70, agentScore: 0 },\n        },\n      },\n    ],\n  ],\n};\n","import type { Hint } from '@walkeros/core';\n\nexport const hints: Hint.Hints = {\n  'ingest-prerequisite': {\n    text: 'The bot transformer reads userAgent from ctx.ingest (path \"ingest.userAgent\" by default). The upstream server source must populate it via config.ingest mapping, otherwise the UA is empty and every event scores 70 (baseline for missing UA).',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                config: {\n                  ingest: {\n                    userAgent: 'req.headers.user-agent',\n                  },\n                },\n              },\n            },\n            transformers: {\n              bot: {\n                package: '@walkeros/server-transformer-bot',\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'output-routing': {\n    text: 'Outputs default to event.user.botScore and event.user.agentScore. Redirect to ingest.* to keep the analytics event clean while still routing on the score downstream. Empty string (or omit) skips writing that field entirely. agentProduct is off by default — set it to enable writing the matched UA substring.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            transformers: {\n              bot: {\n                package: '@walkeros/server-transformer-bot',\n                config: {\n                  settings: {\n                    output: {\n                      botScore: 'ingest.bot.score',\n                      agentScore: 'ingest.bot.agent',\n                      agentProduct: 'user.agentProduct',\n                    },\n                  },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'destination-filtering': {\n    text: 'Recommended destination-mapping recipes. Drop all bots: botScore > 50. Drop crawlers but keep user-action AI traffic: botScore > 50 AND agentProduct NOT LIKE \"%-User\". AI traffic report: group by agentProduct WHERE agentScore > 50. The transformer never drops events — filtering is always a destination decision.',\n  },\n  'detection-scope': {\n    text: 'v1 is UA-only: wraps isbot (curl, wget, headless Chrome defaults, well-known crawlers) plus a curated AI-agent UA map (OpenAI, Anthropic, Perplexity, Mistral, Meta, Google, Apple, Amazon, DuckDuckGo, ByteDance, Common Crawl). It will NOT catch: residential-proxy + stealth Chrome + realistic behavior; reverse-DNS-verified search engines; client-side runtime tells. v1.1 adds header consistency heuristics (Sec-Fetch, Sec-CH-UA, Accept-Language) with proper GREASE handling. For commercial-grade detection use Cloudflare Bot Management, DataDome, or HUMAN.',\n  },\n};\n"],"mappings":"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","names":["import_dev"]}

package/dist/dev.mjs

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=(t,r)=>{for(var o in r)e(t,o,{get:r[o],enumerable:!0})},r={};t(r,{SettingsSchema:()=>a,settings:()=>s});import{zodToSchema as o}from"@walkeros/core/dev";import{z as n}from"@walkeros/core/dev";var i=n.union([n.string().describe('Dot-notation path like "ingest.userAgent"'),n.object({key:n.string().optional(),value:n.unknown().optional(),fn:n.string().optional()}).describe("Mapping value object")]),a=n.object({input:n.object({userAgent:i.optional(),ip:i.optional(),acceptLanguage:i.optional(),acceptEncoding:i.optional(),secFetchSite:i.optional(),secFetchMode:i.optional(),secFetchDest:i.optional(),secFetchUser:i.optional(),secChUa:i.optional(),secChUaMobile:i.optional(),secChUaPlatform:i.optional()}).optional().describe("Input signal sources, resolved via getMappingValue against { event, ingest }. v1 only reads userAgent; other fields reserved for v1.1 header heuristics."),output:n.object({botScore:n.string().optional().describe('Path for bot score (0-99, higher = more bot). Default: "user.botScore". Use "ingest.*" to route to pipeline scratch instead of the event. Empty string or omit = skip.'),agentScore:n.string().optional().describe('Path for AI agent score (0-99). v1 emits 0 (no match) or 95 (UA-map match). Default: "user.agentScore".'),agentProduct:n.string().optional().describe('Path for matched UA substring (e.g. "ChatGPT-User"). Off by default — set to enable.')}).optional().describe("Output paths for bot/agent annotations.")}).describe("Bot detection transformer: annotates events with bot and AI-agent scores."),s=o(a),c={};t(c,{step:()=>l});var l={};t(l,{chatgptUserAgent:()=>d,curlClient:()=>h,gptBotCrawler:()=>u,humanChrome:()=>p,missingUA:()=>b});var g={name:"page view",data:{title:"Home",id:"/"},id:"ev-1700000600",trigger:"load",entity:"page",action:"view",timestamp:1700000600,source:{type:"express",platform:"server"}},p={title:"Human visitor (Chrome)",description:"Modern Chrome UA. No bot or agent signals.",in:{...g},out:[["return",{event:{...g,user:{botScore:0,agentScore:0}}}]]},u={title:"GPTBot training crawler",description:"OpenAI training crawler. Both botScore and agentScore are high.",in:{...g,id:"ev-1700000601"},out:[["return",{event:{...g,id:"ev-1700000601",user:{botScore:95,agentScore:95}}}]]},d={title:"ChatGPT-User (user-action AI)",description:"A real human routed an AI to fetch this page. botScore high but lower than crawlers — agentProduct lets destinations keep this traffic.",in:{...g,id:"ev-1700000602"},out:[["return",{event:{...g,id:"ev-1700000602",user:{botScore:90,agentScore:95}}}]]},h={public:!1,description:"curl client — caught by isbot. agentScore zero.",in:{...g,id:"ev-1700000603"},out:[["return",{event:{...g,id:"ev-1700000603",user:{botScore:80,agentScore:0}}}]]},b={public:!1,description:"No User-Agent — baseline 70 (UA stripping is overwhelmingly bots or hardened privacy tools).",in:{...g,id:"ev-1700000604"},out:[["return",{event:{...g,id:"ev-1700000604",user:{botScore:70,agentScore:0}}}]]},m={"ingest-prerequisite":{text:'The bot transformer reads userAgent from ctx.ingest (path "ingest.userAgent" by default). The upstream server source must populate it via config.ingest mapping, otherwise the UA is empty and every event scores 70 (baseline for missing UA).',code:[{lang:"json",code:JSON.stringify({sources:{express:{package:"@walkeros/server-source-express",config:{ingest:{userAgent:"req.headers.user-agent"}}}},transformers:{bot:{package:"@walkeros/server-transformer-bot"}}},null,2)}]},"output-routing":{text:"Outputs default to event.user.botScore and event.user.agentScore. Redirect to ingest.* to keep the analytics event clean while still routing on the score downstream. Empty string (or omit) skips writing that field entirely. agentProduct is off by default — set it to enable writing the matched UA substring.",code:[{lang:"json",code:JSON.stringify({transformers:{bot:{package:"@walkeros/server-transformer-bot",config:{settings:{output:{botScore:"ingest.bot.score",agentScore:"ingest.bot.agent",agentProduct:"user.agentProduct"}}}}}},null,2)}]},"destination-filtering":{text:'Recommended destination-mapping recipes. Drop all bots: botScore > 50. Drop crawlers but keep user-action AI traffic: botScore > 50 AND agentProduct NOT LIKE "%-User". AI traffic report: group by agentProduct WHERE agentScore > 50. The transformer never drops events — filtering is always a destination decision.'},"detection-scope":{text:"v1 is UA-only: wraps isbot (curl, wget, headless Chrome defaults, well-known crawlers) plus a curated AI-agent UA map (OpenAI, Anthropic, Perplexity, Mistral, Meta, Google, Apple, Amazon, DuckDuckGo, ByteDance, Common Crawl). It will NOT catch: residential-proxy + stealth Chrome + realistic behavior; reverse-DNS-verified search engines; client-side runtime tells. v1.1 adds header consistency heuristics (Sec-Fetch, Sec-CH-UA, Accept-Language) with proper GREASE handling. For commercial-grade detection use Cloudflare Bot Management, DataDome, or HUMAN."}};export{c as examples,m as hints,r as schemas};//# sourceMappingURL=dev.mjs.map

package/dist/dev.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schemas/index.ts","../src/schemas/settings.ts","../src/examples/index.ts","../src/examples/step.ts","../src/hints.ts"],"sourcesContent":["import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport const settings = zodToSchema(SettingsSchema);\n","import { z } from '@walkeros/core/dev';\n\nconst MappingValueSchema = z.union([\n  z.string().describe('Dot-notation path like \"ingest.userAgent\"'),\n  z\n    .object({\n      key: z.string().optional(),\n      value: z.unknown().optional(),\n      fn: z.string().optional(),\n    })\n    .describe('Mapping value object'),\n]);\n\nexport const SettingsSchema = z\n  .object({\n    input: z\n      .object({\n        userAgent: MappingValueSchema.optional(),\n        ip: MappingValueSchema.optional(),\n        acceptLanguage: MappingValueSchema.optional(),\n        acceptEncoding: MappingValueSchema.optional(),\n        secFetchSite: MappingValueSchema.optional(),\n        secFetchMode: MappingValueSchema.optional(),\n        secFetchDest: MappingValueSchema.optional(),\n        secFetchUser: MappingValueSchema.optional(),\n        secChUa: MappingValueSchema.optional(),\n        secChUaMobile: MappingValueSchema.optional(),\n        secChUaPlatform: MappingValueSchema.optional(),\n      })\n      .optional()\n      .describe(\n        'Input signal sources, resolved via getMappingValue against { event, ingest }. v1 only reads userAgent; other fields reserved for v1.1 header heuristics.',\n      ),\n    output: z\n      .object({\n        botScore: z\n          .string()\n          .optional()\n          .describe(\n            'Path for bot score (0-99, higher = more bot). Default: \"user.botScore\". Use \"ingest.*\" to route to pipeline scratch instead of the event. Empty string or omit = skip.',\n          ),\n        agentScore: z\n          .string()\n          .optional()\n          .describe(\n            'Path for AI agent score (0-99). v1 emits 0 (no match) or 95 (UA-map match). Default: \"user.agentScore\".',\n          ),\n        agentProduct: z\n          .string()\n          .optional()\n          .describe(\n            'Path for matched UA substring (e.g. \"ChatGPT-User\"). Off by default — set to enable.',\n          ),\n      })\n      .optional()\n      .describe('Output paths for bot/agent annotations.'),\n  })\n  .describe(\n    'Bot detection transformer: annotates events with bot and AI-agent scores.',\n  );\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","export * as step from './step';\n","import type { Flow } from '@walkeros/core';\n\nconst baseEvent = {\n  name: 'page view',\n  data: { title: 'Home', id: '/' },\n  id: 'ev-1700000600',\n  trigger: 'load',\n  entity: 'page',\n  action: 'view',\n  timestamp: 1700000600,\n  source: { type: 'express', platform: 'server' as const },\n};\n\n/** Real Chrome — botScore 0, agentScore 0. */\nexport const humanChrome: Flow.StepExample = {\n  title: 'Human visitor (Chrome)',\n  description: 'Modern Chrome UA. No bot or agent signals.',\n  in: { ...baseEvent },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          user: { botScore: 0, agentScore: 0 },\n        },\n      },\n    ],\n  ],\n};\n\n/** GPTBot — training crawler. */\nexport const gptBotCrawler: Flow.StepExample = {\n  title: 'GPTBot training crawler',\n  description:\n    'OpenAI training crawler. Both botScore and agentScore are high.',\n  in: { ...baseEvent, id: 'ev-1700000601' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000601',\n          user: { botScore: 95, agentScore: 95 },\n        },\n      },\n    ],\n  ],\n};\n\n/** ChatGPT-User — user-action AI agent. */\nexport const chatgptUserAgent: Flow.StepExample = {\n  title: 'ChatGPT-User (user-action AI)',\n  description:\n    'A real human routed an AI to fetch this page. botScore high but lower than crawlers — agentProduct lets destinations keep this traffic.',\n  in: { ...baseEvent, id: 'ev-1700000602' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000602',\n          user: { botScore: 90, agentScore: 95 },\n        },\n      },\n    ],\n  ],\n};\n\n/** curl — caught by isbot. */\nexport const curlClient: Flow.StepExample = {\n  public: false,\n  description: 'curl client — caught by isbot. agentScore zero.',\n  in: { ...baseEvent, id: 'ev-1700000603' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000603',\n          user: { botScore: 80, agentScore: 0 },\n        },\n      },\n    ],\n  ],\n};\n\n/** Empty / missing UA — score 70 (suspicious; real browsers rarely strip UA). */\nexport const missingUA: Flow.StepExample = {\n  public: false,\n  description:\n    'No User-Agent — baseline 70 (UA stripping is overwhelmingly bots or hardened privacy tools).',\n  in: { ...baseEvent, id: 'ev-1700000604' },\n  out: [\n    [\n      'return',\n      {\n        event: {\n          ...baseEvent,\n          id: 'ev-1700000604',\n          user: { botScore: 70, agentScore: 0 },\n        },\n      },\n    ],\n  ],\n};\n","import type { Hint } from '@walkeros/core';\n\nexport const hints: Hint.Hints = {\n  'ingest-prerequisite': {\n    text: 'The bot transformer reads userAgent from ctx.ingest (path \"ingest.userAgent\" by default). The upstream server source must populate it via config.ingest mapping, otherwise the UA is empty and every event scores 70 (baseline for missing UA).',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            sources: {\n              express: {\n                package: '@walkeros/server-source-express',\n                config: {\n                  ingest: {\n                    userAgent: 'req.headers.user-agent',\n                  },\n                },\n              },\n            },\n            transformers: {\n              bot: {\n                package: '@walkeros/server-transformer-bot',\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'output-routing': {\n    text: 'Outputs default to event.user.botScore and event.user.agentScore. Redirect to ingest.* to keep the analytics event clean while still routing on the score downstream. Empty string (or omit) skips writing that field entirely. agentProduct is off by default — set it to enable writing the matched UA substring.',\n    code: [\n      {\n        lang: 'json',\n        code: JSON.stringify(\n          {\n            transformers: {\n              bot: {\n                package: '@walkeros/server-transformer-bot',\n                config: {\n                  settings: {\n                    output: {\n                      botScore: 'ingest.bot.score',\n                      agentScore: 'ingest.bot.agent',\n                      agentProduct: 'user.agentProduct',\n                    },\n                  },\n                },\n              },\n            },\n          },\n          null,\n          2,\n        ),\n      },\n    ],\n  },\n  'destination-filtering': {\n    text: 'Recommended destination-mapping recipes. Drop all bots: botScore > 50. Drop crawlers but keep user-action AI traffic: botScore > 50 AND agentProduct NOT LIKE \"%-User\". AI traffic report: group by agentProduct WHERE agentScore > 50. The transformer never drops events — filtering is always a destination decision.',\n  },\n  'detection-scope': {\n    text: 'v1 is UA-only: wraps isbot (curl, wget, headless Chrome defaults, well-known crawlers) plus a curated AI-agent UA map (OpenAI, Anthropic, Perplexity, Mistral, Meta, Google, Apple, Amazon, DuckDuckGo, ByteDance, Common Crawl). It will NOT catch: residential-proxy + stealth Chrome + realistic behavior; reverse-DNS-verified search engines; client-side runtime tells. v1.1 adds header consistency heuristics (Sec-Fetch, Sec-CH-UA, Accept-Language) with proper GREASE handling. For commercial-grade detection use Cloudflare Bot Management, DataDome, or HUMAN.',\n  },\n};\n"],"mappings":"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","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import { Mapping, Transformer } from '@walkeros/core';
+
+/**
+ * Input signal sources. Each is a Mapping.Value resolved via getMappingValue
+ * against { event, ingest }.
+ *
+ * v1 only reads `userAgent`. The remaining fields are reserved for v1.1
+ * (header consistency heuristics) so the public schema stays stable.
+ */
+interface BotInput {
+    userAgent?: Mapping.Value;
+    ip?: Mapping.Value;
+    acceptLanguage?: Mapping.Value;
+    acceptEncoding?: Mapping.Value;
+    secFetchSite?: Mapping.Value;
+    secFetchMode?: Mapping.Value;
+    secFetchDest?: Mapping.Value;
+    secFetchUser?: Mapping.Value;
+    secChUa?: Mapping.Value;
+    secChUaMobile?: Mapping.Value;
+    secChUaPlatform?: Mapping.Value;
+}
+/**
+ * Output paths. Empty string or omitted = skip writing that field.
+ * Paths starting with `ingest.` route to context.ingest (pipeline scratch);
+ * everything else routes to the event.
+ */
+interface BotOutput {
+    botScore?: string;
+    agentScore?: string;
+    agentProduct?: string;
+}
+interface BotSettings {
+    input?: BotInput;
+    output?: BotOutput;
+}
+
+declare const transformerBot: Transformer.Init<Transformer.Types<BotSettings>>;
+
+export { type BotInput, type BotOutput, type BotSettings, transformerBot as default, transformerBot };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { Mapping, Transformer } from '@walkeros/core';
+
+/**
+ * Input signal sources. Each is a Mapping.Value resolved via getMappingValue
+ * against { event, ingest }.
+ *
+ * v1 only reads `userAgent`. The remaining fields are reserved for v1.1
+ * (header consistency heuristics) so the public schema stays stable.
+ */
+interface BotInput {
+    userAgent?: Mapping.Value;
+    ip?: Mapping.Value;
+    acceptLanguage?: Mapping.Value;
+    acceptEncoding?: Mapping.Value;
+    secFetchSite?: Mapping.Value;
+    secFetchMode?: Mapping.Value;
+    secFetchDest?: Mapping.Value;
+    secFetchUser?: Mapping.Value;
+    secChUa?: Mapping.Value;
+    secChUaMobile?: Mapping.Value;
+    secChUaPlatform?: Mapping.Value;
+}
+/**
+ * Output paths. Empty string or omitted = skip writing that field.
+ * Paths starting with `ingest.` route to context.ingest (pipeline scratch);
+ * everything else routes to the event.
+ */
+interface BotOutput {
+    botScore?: string;
+    agentScore?: string;
+    agentProduct?: string;
+}
+interface BotSettings {
+    input?: BotInput;
+    output?: BotOutput;
+}
+
+declare const transformerBot: Transformer.Init<Transformer.Types<BotSettings>>;
+
+export { type BotInput, type BotOutput, type BotSettings, transformerBot as default, transformerBot };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var e,t=Object.defineProperty,o=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,c=Object.prototype.hasOwnProperty,a={};((e,o)=>{for(var r in o)t(e,r,{get:o[r],enumerable:!0})})(a,{default:()=>d,transformerBot:()=>d}),module.exports=(e=a,((e,a,n,s)=>{if(a&&"object"==typeof a||"function"==typeof a)for(let p of r(a))c.call(e,p)||p===n||t(e,p,{get:()=>a[p],enumerable:!(s=o(a,p))||s.enumerable});return e})(t({},"__esModule",{value:!0}),e));var n=require("@walkeros/core"),s=require("isbot"),p=[{match:"ChatGPT-User",product:"ChatGPT-User",purpose:"user-action"},{match:"ChatGPT-Agent",product:"ChatGPT-Agent",purpose:"user-action"},{match:"OAI-SearchBot",product:"OAI-SearchBot",purpose:"search-index"},{match:"GPTBot",product:"GPTBot",purpose:"training"},{match:"Claude-SearchBot",product:"Claude-SearchBot",purpose:"search-index"},{match:"Claude-User",product:"Claude-User",purpose:"user-action"},{match:"Claude-Code",product:"Claude-Code",purpose:"user-action"},{match:"ClaudeBot",product:"ClaudeBot",purpose:"training"},{match:"anthropic-ai",product:"anthropic-ai",purpose:"training"},{match:"Perplexity-User",product:"Perplexity-User",purpose:"user-action"},{match:"PerplexityBot",product:"PerplexityBot",purpose:"search-index"},{match:"MistralAI-User",product:"MistralAI-User",purpose:"user-action"},{match:"Meta-ExternalFetcher",product:"Meta-ExternalFetcher",purpose:"user-action"},{match:"Meta-ExternalAgent",product:"Meta-ExternalAgent",purpose:"training"},{match:"Google-CloudVertexBot",product:"Google-CloudVertexBot",purpose:"training"},{match:"Google-Extended",product:"Google-Extended",purpose:"training"},{match:"Applebot-Extended",product:"Applebot-Extended",purpose:"training"},{match:"Amazonbot",product:"Amazonbot",purpose:"training"},{match:"DuckAssistBot",product:"DuckAssistBot",purpose:"user-action"},{match:"Bytespider",product:"Bytespider",purpose:"training"},{match:"CCBot",product:"CCBot",purpose:"training"}];function u(e){if(!e)return{botScore:70,agentScore:0,agentProduct:void 0};const t=function(e){const t=e.toLowerCase(),o=p.find(e=>t.includes(e.match.toLowerCase()));return{isBot:!e||(0,s.isbot)(e)||void 0!==o,agent:o?{product:o.product,purpose:o.purpose}:void 0}}(e);let o=0;return t.agent?o="user-action"===t.agent.purpose?90:95:t.isBot&&(o=80),{botScore:o,agentScore:t.agent?95:0,agentProduct:t.agent?.product}}var i={userAgent:"ingest.userAgent",ip:"ingest.ip",acceptLanguage:"ingest.acceptLanguage",acceptEncoding:"ingest.acceptEncoding",secFetchSite:"ingest.secFetchSite",secFetchMode:"ingest.secFetchMode",secFetchDest:"ingest.secFetchDest",secFetchUser:"ingest.secFetchUser",secChUa:"ingest.secChUa",secChUaMobile:"ingest.secChUaMobile",secChUaPlatform:"ingest.secChUaPlatform"},g={botScore:"user.botScore",agentScore:"user.agentScore",agentProduct:""};var d=e=>{const{config:t}=e,o=t.settings??{},r={...i,...o.input??{}},c={...g,...o.output??{}};return{type:"bot",config:t,async push(e,t){const{ingest:o,collector:a}=t,s={event:e,ingest:o},p=await(0,n.getMappingValue)(s,r.userAgent,{collector:a}),i=u("string"==typeof p?p:"");let g=e;const d=(e,t)=>{e&&void 0!==t&&(e.startsWith("ingest.")?function(e,t,o){const r=t.split(".");let c=e;for(let e=0;e<r.length-1;e++){const t=r[e],o=c[t];"object"==typeof o&&null!==o||(c[t]={}),c=c[t]}c[r[r.length-1]]=o}(o,e.slice(7),t):g=(0,n.setByPath)(g,e,t))};return d(c.botScore??"",i.botScore),d(c.agentScore??"",i.agentScore),d(c.agentProduct??"",i.agentProduct),{event:g}}}};//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/transformer.ts","../src/detect/ua.ts","../src/data/agents.ts","../src/detect/score.ts"],"sourcesContent":["export { transformerBot } from './transformer';\nexport type { BotSettings, BotInput, BotOutput } from './types';\nexport { transformerBot as default } from './transformer';\n","import type { Transformer } from '@walkeros/core';\nimport { getMappingValue, setByPath } from '@walkeros/core';\nimport { computeScore } from './detect/score';\nimport type { BotInput, BotOutput, BotSettings } from './types';\n\nconst DEFAULT_INPUT: Required<BotInput> = {\n  userAgent: 'ingest.userAgent',\n  ip: 'ingest.ip',\n  acceptLanguage: 'ingest.acceptLanguage',\n  acceptEncoding: 'ingest.acceptEncoding',\n  secFetchSite: 'ingest.secFetchSite',\n  secFetchMode: 'ingest.secFetchMode',\n  secFetchDest: 'ingest.secFetchDest',\n  secFetchUser: 'ingest.secFetchUser',\n  secChUa: 'ingest.secChUa',\n  secChUaMobile: 'ingest.secChUaMobile',\n  secChUaPlatform: 'ingest.secChUaPlatform',\n};\n\nconst DEFAULT_OUTPUT: Required<BotOutput> = {\n  botScore: 'user.botScore',\n  agentScore: 'user.agentScore',\n  agentProduct: '', // off by default\n};\n\n/**\n * Mutating dot-path setter for ingest writes.\n *\n * We can't use @walkeros/core setByPath here: it clones-and-returns (immutable),\n * but ingest is the pipeline's mutable scratch context. We need in-place writes\n * so subsequent transformers in the chain see the values.\n */\nfunction setNestedPath(\n  obj: Record<string, unknown>,\n  path: string,\n  value: unknown,\n): void {\n  const keys = path.split('.');\n  let cur: Record<string, unknown> = obj;\n  for (let i = 0; i < keys.length - 1; i++) {\n    const k = keys[i];\n    const next = cur[k];\n    if (typeof next !== 'object' || next === null) cur[k] = {};\n    cur = cur[k] as Record<string, unknown>;\n  }\n  cur[keys[keys.length - 1]] = value;\n}\n\nexport const transformerBot: Transformer.Init<\n  Transformer.Types<BotSettings>\n> = (context) => {\n  const { config } = context;\n  const settings: BotSettings = config.settings ?? {};\n  const input: Required<BotInput> = {\n    ...DEFAULT_INPUT,\n    ...(settings.input ?? {}),\n  };\n  const output: BotOutput = {\n    ...DEFAULT_OUTPUT,\n    ...(settings.output ?? {}),\n  };\n\n  return {\n    // Init's input config type is Partial<Settings>; the instance config type\n    // is Settings. Same cast pattern the fingerprint transformer uses.\n    type: 'bot',\n    config: config as Transformer.Config<Transformer.Types<BotSettings>>,\n\n    async push(event, ctx) {\n      const { ingest, collector } = ctx;\n      const source = { event, ingest };\n\n      // v1 only reads userAgent. Other input fields are reserved for v1.1\n      // (header heuristics); resolved-but-unused here would be wasteful, so\n      // they are intentionally not read yet.\n      const uaValue = await getMappingValue(source, input.userAgent, {\n        collector,\n      });\n      const ua = typeof uaValue === 'string' ? uaValue : '';\n      const score = computeScore(ua);\n\n      let nextEvent = event;\n\n      const writeOutput = (path: string, value: unknown) => {\n        if (!path || value === undefined) return;\n        if (path.startsWith('ingest.')) {\n          setNestedPath(ingest, path.slice('ingest.'.length), value);\n        } else {\n          nextEvent = setByPath(nextEvent, path, value);\n        }\n      };\n\n      writeOutput(output.botScore ?? '', score.botScore);\n      writeOutput(output.agentScore ?? '', score.agentScore);\n      writeOutput(output.agentProduct ?? '', score.agentProduct);\n\n      return { event: nextEvent };\n    },\n  };\n};\n","import { isbot } from 'isbot';\nimport { agents, type AgentEntry } from '../data/agents';\n\nexport interface UAResult {\n  isBot: boolean;\n  agent?: { product: string; purpose: AgentEntry['purpose'] };\n}\n\nexport function detectUA(ua: string): UAResult {\n  const lower = ua.toLowerCase();\n  const matched = agents.find((a) => lower.includes(a.match.toLowerCase()));\n  return {\n    isBot: !ua || isbot(ua) || matched !== undefined,\n    agent: matched\n      ? { product: matched.product, purpose: matched.purpose }\n      : undefined,\n  };\n}\n","/**\n * Curated AI agent UA-substring map (2026-Q2).\n *\n * Each entry: substring matched case-insensitively against the User-Agent,\n * a product label written to event.user.agentProduct, and the purpose category.\n *\n * Purpose semantics:\n *   - 'training'     — crawls for model training; usually filter from analytics\n *   - 'search-index' — crawls to power AI search answers; AEO-relevant\n *   - 'user-action'  — fetch initiated by a human via an AI tool; often kept as traffic\n *\n * Order matters: first-hit wins. More-specific entries must precede broader ones.\n *\n * Vendor docs of record (verified 2026-05):\n *   OpenAI:        https://platform.openai.com/docs/bots\n *   Anthropic:     https://support.claude.com/en/articles/8896518\n *   Perplexity:    https://docs.perplexity.ai/guides/bots\n *   Meta:          https://developers.facebook.com/docs/sharing/webmasters/web-crawlers\n *   Google:        https://developers.google.com/search/docs/crawling-indexing/google-common-crawlers\n *   Apple:         https://support.apple.com/en-us/119829\n *   DuckDuckGo:    https://duckduckgo.com/duckduckbot\n *   Common Crawl:  https://commoncrawl.org/faq\n *   Amazon:        https://developer.amazon.com/amazonbot\n *\n * Community cross-reference: https://github.com/ai-robots-txt/ai.robots.txt\n *\n * Reviewed quarterly — see /workspaces/developer/docs/research/2026-05-13-bot-detection.md.\n */\nexport interface AgentEntry {\n  match: string;\n  product: string;\n  purpose: 'training' | 'search-index' | 'user-action';\n}\n\nexport const agents: AgentEntry[] = [\n  // --- OpenAI ---\n  { match: 'ChatGPT-User', product: 'ChatGPT-User', purpose: 'user-action' },\n  { match: 'ChatGPT-Agent', product: 'ChatGPT-Agent', purpose: 'user-action' },\n  { match: 'OAI-SearchBot', product: 'OAI-SearchBot', purpose: 'search-index' },\n  { match: 'GPTBot', product: 'GPTBot', purpose: 'training' },\n\n  // --- Anthropic ---\n  // Claude-SearchBot must precede Claude-User (defensive specificity for composite UAs)\n  {\n    match: 'Claude-SearchBot',\n    product: 'Claude-SearchBot',\n    purpose: 'search-index',\n  },\n  { match: 'Claude-User', product: 'Claude-User', purpose: 'user-action' },\n  { match: 'Claude-Code', product: 'Claude-Code', purpose: 'user-action' },\n  { match: 'ClaudeBot', product: 'ClaudeBot', purpose: 'training' },\n  // Legacy: only used by older Anthropic crawlers; kept for back-compat with old logs.\n  { match: 'anthropic-ai', product: 'anthropic-ai', purpose: 'training' },\n\n  // --- Perplexity ---\n  {\n    match: 'Perplexity-User',\n    product: 'Perplexity-User',\n    purpose: 'user-action',\n  },\n  {\n    match: 'PerplexityBot',\n    product: 'PerplexityBot',\n    purpose: 'search-index',\n  },\n\n  // --- Mistral ---\n  {\n    match: 'MistralAI-User',\n    product: 'MistralAI-User',\n    purpose: 'user-action',\n  },\n\n  // --- Meta ---\n  {\n    match: 'Meta-ExternalFetcher',\n    product: 'Meta-ExternalFetcher',\n    purpose: 'user-action',\n  },\n  {\n    match: 'Meta-ExternalAgent',\n    product: 'Meta-ExternalAgent',\n    purpose: 'training',\n  },\n\n  // --- Google ---\n  {\n    match: 'Google-CloudVertexBot',\n    product: 'Google-CloudVertexBot',\n    purpose: 'training',\n  },\n  {\n    match: 'Google-Extended',\n    product: 'Google-Extended',\n    purpose: 'training',\n  },\n\n  // --- Apple ---\n  {\n    match: 'Applebot-Extended',\n    product: 'Applebot-Extended',\n    purpose: 'training',\n  },\n\n  // --- Amazon ---\n  { match: 'Amazonbot', product: 'Amazonbot', purpose: 'training' },\n\n  // --- DuckDuckGo ---\n  {\n    match: 'DuckAssistBot',\n    product: 'DuckAssistBot',\n    purpose: 'user-action',\n  },\n\n  // --- ByteDance ---\n  { match: 'Bytespider', product: 'Bytespider', purpose: 'training' },\n\n  // --- Common Crawl ---\n  { match: 'CCBot', product: 'CCBot', purpose: 'training' },\n];\n","import { detectUA } from './ua';\n\nexport interface ScoreResult {\n  /** 0-99, higher = more bot. v1 emits discrete values: 0, 70, 80, 90, 95. */\n  botScore: number;\n  /**\n   * 0-99, higher = more likely an AI agent. v1 emits only 0 or 95\n   * (binary UA-map match). Graduated values (e.g. 70 for unverified UA\n   * claim, 99 for IP-reverse-DNS verified) are planned for v1.1.\n   */\n  agentScore: number;\n  /** Matched AI agent UA substring, when one was found. */\n  agentProduct?: string;\n}\n\n/**\n * v1: UA-only.\n *\n * botScore baseline:\n *   - Empty UA            → 70 (real browsers rarely strip UA)\n *   - AI training crawler → 95\n *   - AI user-action      → 90\n *   - isbot true          → 80\n *   - Otherwise           → 0\n *\n * Header heuristics (Sec-Fetch missing, Sec-CH-UA major mismatch,\n * Accept-Language stripping) are intentionally deferred to v1.1 —\n * see the README \"Not in v1\" section and the research file.\n */\nexport function computeScore(ua: string): ScoreResult {\n  if (!ua) {\n    return { botScore: 70, agentScore: 0, agentProduct: undefined };\n  }\n\n  const uaResult = detectUA(ua);\n\n  let botScore = 0;\n  if (uaResult.agent) {\n    botScore = uaResult.agent.purpose === 'user-action' ? 90 : 95;\n  } else if (uaResult.isBot) {\n    botScore = 80;\n  }\n\n  return {\n    botScore,\n    agentScore: uaResult.agent ? 95 : 0,\n    agentProduct: uaResult.agent?.product,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACCA,kBAA2C;;;ACD3C,mBAAsB;;;ACkCf,IAAM,SAAuB;AAAA;AAAA,EAElC,EAAE,OAAO,gBAAgB,SAAS,gBAAgB,SAAS,cAAc;AAAA,EACzE,EAAE,OAAO,iBAAiB,SAAS,iBAAiB,SAAS,cAAc;AAAA,EAC3E,EAAE,OAAO,iBAAiB,SAAS,iBAAiB,SAAS,eAAe;AAAA,EAC5E,EAAE,OAAO,UAAU,SAAS,UAAU,SAAS,WAAW;AAAA;AAAA;AAAA,EAI1D;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA,EACA,EAAE,OAAO,eAAe,SAAS,eAAe,SAAS,cAAc;AAAA,EACvE,EAAE,OAAO,eAAe,SAAS,eAAe,SAAS,cAAc;AAAA,EACvE,EAAE,OAAO,aAAa,SAAS,aAAa,SAAS,WAAW;AAAA;AAAA,EAEhE,EAAE,OAAO,gBAAgB,SAAS,gBAAgB,SAAS,WAAW;AAAA;AAAA,EAGtE;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA,EACA;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA;AAAA,EAGA;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA;AAAA,EAGA;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA,EACA;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA;AAAA,EAGA;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA,EACA;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA;AAAA,EAGA;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA;AAAA,EAGA,EAAE,OAAO,aAAa,SAAS,aAAa,SAAS,WAAW;AAAA;AAAA,EAGhE;AAAA,IACE,OAAO;AAAA,IACP,SAAS;AAAA,IACT,SAAS;AAAA,EACX;AAAA;AAAA,EAGA,EAAE,OAAO,cAAc,SAAS,cAAc,SAAS,WAAW;AAAA;AAAA,EAGlE,EAAE,OAAO,SAAS,SAAS,SAAS,SAAS,WAAW;AAC1D;;;AD/GO,SAAS,SAAS,IAAsB;AAC7C,QAAM,QAAQ,GAAG,YAAY;AAC7B,QAAM,UAAU,OAAO,KAAK,CAAC,MAAM,MAAM,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC;AACxE,SAAO;AAAA,IACL,OAAO,CAAC,UAAM,oBAAM,EAAE,KAAK,YAAY;AAAA,IACvC,OAAO,UACH,EAAE,SAAS,QAAQ,SAAS,SAAS,QAAQ,QAAQ,IACrD;AAAA,EACN;AACF;;;AEYO,SAAS,aAAa,IAAyB;AACpD,MAAI,CAAC,IAAI;AACP,WAAO,EAAE,UAAU,IAAI,YAAY,GAAG,cAAc,OAAU;AAAA,EAChE;AAEA,QAAM,WAAW,SAAS,EAAE;AAE5B,MAAI,WAAW;AACf,MAAI,SAAS,OAAO;AAClB,eAAW,SAAS,MAAM,YAAY,gBAAgB,KAAK;AAAA,EAC7D,WAAW,SAAS,OAAO;AACzB,eAAW;AAAA,EACb;AAEA,SAAO;AAAA,IACL;AAAA,IACA,YAAY,SAAS,QAAQ,KAAK;AAAA,IAClC,cAAc,SAAS,OAAO;AAAA,EAChC;AACF;;;AH3CA,IAAM,gBAAoC;AAAA,EACxC,WAAW;AAAA,EACX,IAAI;AAAA,EACJ,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,cAAc;AAAA,EACd,cAAc;AAAA,EACd,cAAc;AAAA,EACd,cAAc;AAAA,EACd,SAAS;AAAA,EACT,eAAe;AAAA,EACf,iBAAiB;AACnB;AAEA,IAAM,iBAAsC;AAAA,EAC1C,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,cAAc;AAAA;AAChB;AASA,SAAS,cACP,KACA,MACA,OACM;AACN,QAAM,OAAO,KAAK,MAAM,GAAG;AAC3B,MAAI,MAA+B;AACnC,WAAS,IAAI,GAAG,IAAI,KAAK,SAAS,GAAG,KAAK;AACxC,UAAM,IAAI,KAAK,CAAC;AAChB,UAAM,OAAO,IAAI,CAAC;AAClB,QAAI,OAAO,SAAS,YAAY,SAAS,KAAM,KAAI,CAAC,IAAI,CAAC;AACzD,UAAM,IAAI,CAAC;AAAA,EACb;AACA,MAAI,KAAK,KAAK,SAAS,CAAC,CAAC,IAAI;AAC/B;AAEO,IAAM,iBAET,CAAC,YAAY;AACf,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,WAAwB,OAAO,YAAY,CAAC;AAClD,QAAM,QAA4B;AAAA,IAChC,GAAG;AAAA,IACH,GAAI,SAAS,SAAS,CAAC;AAAA,EACzB;AACA,QAAM,SAAoB;AAAA,IACxB,GAAG;AAAA,IACH,GAAI,SAAS,UAAU,CAAC;AAAA,EAC1B;AAEA,SAAO;AAAA;AAAA;AAAA,IAGL,MAAM;AAAA,IACN;AAAA,IAEA,MAAM,KAAK,OAAO,KAAK;AACrB,YAAM,EAAE,QAAQ,UAAU,IAAI;AAC9B,YAAM,SAAS,EAAE,OAAO,OAAO;AAK/B,YAAM,UAAU,UAAM,6BAAgB,QAAQ,MAAM,WAAW;AAAA,QAC7D;AAAA,MACF,CAAC;AACD,YAAM,KAAK,OAAO,YAAY,WAAW,UAAU;AACnD,YAAM,QAAQ,aAAa,EAAE;AAE7B,UAAI,YAAY;AAEhB,YAAM,cAAc,CAAC,MAAc,UAAmB;AACpD,YAAI,CAAC,QAAQ,UAAU,OAAW;AAClC,YAAI,KAAK,WAAW,SAAS,GAAG;AAC9B,wBAAc,QAAQ,KAAK,MAAM,UAAU,MAAM,GAAG,KAAK;AAAA,QAC3D,OAAO;AACL,0BAAY,uBAAU,WAAW,MAAM,KAAK;AAAA,QAC9C;AAAA,MACF;AAEA,kBAAY,OAAO,YAAY,IAAI,MAAM,QAAQ;AACjD,kBAAY,OAAO,cAAc,IAAI,MAAM,UAAU;AACrD,kBAAY,OAAO,gBAAgB,IAAI,MAAM,YAAY;AAEzD,aAAO,EAAE,OAAO,UAAU;AAAA,IAC5B;AAAA,EACF;AACF;","names":[]}

package/dist/index.mjs

@@ -0,0 +1 @@
+import{getMappingValue as t,setByPath as e}from"@walkeros/core";import{isbot as o}from"isbot";var r=[{match:"ChatGPT-User",product:"ChatGPT-User",purpose:"user-action"},{match:"ChatGPT-Agent",product:"ChatGPT-Agent",purpose:"user-action"},{match:"OAI-SearchBot",product:"OAI-SearchBot",purpose:"search-index"},{match:"GPTBot",product:"GPTBot",purpose:"training"},{match:"Claude-SearchBot",product:"Claude-SearchBot",purpose:"search-index"},{match:"Claude-User",product:"Claude-User",purpose:"user-action"},{match:"Claude-Code",product:"Claude-Code",purpose:"user-action"},{match:"ClaudeBot",product:"ClaudeBot",purpose:"training"},{match:"anthropic-ai",product:"anthropic-ai",purpose:"training"},{match:"Perplexity-User",product:"Perplexity-User",purpose:"user-action"},{match:"PerplexityBot",product:"PerplexityBot",purpose:"search-index"},{match:"MistralAI-User",product:"MistralAI-User",purpose:"user-action"},{match:"Meta-ExternalFetcher",product:"Meta-ExternalFetcher",purpose:"user-action"},{match:"Meta-ExternalAgent",product:"Meta-ExternalAgent",purpose:"training"},{match:"Google-CloudVertexBot",product:"Google-CloudVertexBot",purpose:"training"},{match:"Google-Extended",product:"Google-Extended",purpose:"training"},{match:"Applebot-Extended",product:"Applebot-Extended",purpose:"training"},{match:"Amazonbot",product:"Amazonbot",purpose:"training"},{match:"DuckAssistBot",product:"DuckAssistBot",purpose:"user-action"},{match:"Bytespider",product:"Bytespider",purpose:"training"},{match:"CCBot",product:"CCBot",purpose:"training"}];function c(t){if(!t)return{botScore:70,agentScore:0,agentProduct:void 0};const e=function(t){const e=t.toLowerCase(),c=r.find(t=>e.includes(t.match.toLowerCase()));return{isBot:!t||o(t)||void 0!==c,agent:c?{product:c.product,purpose:c.purpose}:void 0}}(t);let c=0;return e.agent?c="user-action"===e.agent.purpose?90:95:e.isBot&&(c=80),{botScore:c,agentScore:e.agent?95:0,agentProduct:e.agent?.product}}var a={userAgent:"ingest.userAgent",ip:"ingest.ip",acceptLanguage:"ingest.acceptLanguage",acceptEncoding:"ingest.acceptEncoding",secFetchSite:"ingest.secFetchSite",secFetchMode:"ingest.secFetchMode",secFetchDest:"ingest.secFetchDest",secFetchUser:"ingest.secFetchUser",secChUa:"ingest.secChUa",secChUaMobile:"ingest.secChUaMobile",secChUaPlatform:"ingest.secChUaPlatform"},n={botScore:"user.botScore",agentScore:"user.agentScore",agentProduct:""};var s=o=>{const{config:r}=o,s=r.settings??{},p={...a,...s.input??{}},u={...n,...s.output??{}};return{type:"bot",config:r,async push(o,r){const{ingest:a,collector:n}=r,s={event:o,ingest:a},i=await t(s,p.userAgent,{collector:n}),d=c("string"==typeof i?i:"");let g=o;const h=(t,o)=>{t&&void 0!==o&&(t.startsWith("ingest.")?function(t,e,o){const r=e.split(".");let c=t;for(let t=0;t<r.length-1;t++){const e=r[t],o=c[e];"object"==typeof o&&null!==o||(c[e]={}),c=c[e]}c[r[r.length-1]]=o}(a,t.slice(7),o):g=e(g,t,o))};return h(u.botScore??"",d.botScore),h(u.agentScore??"",d.agentScore),h(u.agentProduct??"",d.agentProduct),{event:g}}}};export{s as default,s as transformerBot};//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transformer.ts","../src/detect/ua.ts","../src/data/agents.ts","../src/detect/score.ts"],"sourcesContent":["import type { Transformer } from '@walkeros/core';\nimport { getMappingValue, setByPath } from '@walkeros/core';\nimport { computeScore } from './detect/score';\nimport type { BotInput, BotOutput, BotSettings } from './types';\n\nconst DEFAULT_INPUT: Required<BotInput> = {\n  userAgent: 'ingest.userAgent',\n  ip: 'ingest.ip',\n  acceptLanguage: 'ingest.acceptLanguage',\n  acceptEncoding: 'ingest.acceptEncoding',\n  secFetchSite: 'ingest.secFetchSite',\n  secFetchMode: 'ingest.secFetchMode',\n  secFetchDest: 'ingest.secFetchDest',\n  secFetchUser: 'ingest.secFetchUser',\n  secChUa: 'ingest.secChUa',\n  secChUaMobile: 'ingest.secChUaMobile',\n  secChUaPlatform: 'ingest.secChUaPlatform',\n};\n\nconst DEFAULT_OUTPUT: Required<BotOutput> = {\n  botScore: 'user.botScore',\n  agentScore: 'user.agentScore',\n  agentProduct: '', // off by default\n};\n\n/**\n * Mutating dot-path setter for ingest writes.\n *\n * We can't use @walkeros/core setByPath here: it clones-and-returns (immutable),\n * but ingest is the pipeline's mutable scratch context. We need in-place writes\n * so subsequent transformers in the chain see the values.\n */\nfunction setNestedPath(\n  obj: Record<string, unknown>,\n  path: string,\n  value: unknown,\n): void {\n  const keys = path.split('.');\n  let cur: Record<string, unknown> = obj;\n  for (let i = 0; i < keys.length - 1; i++) {\n    const k = keys[i];\n    const next = cur[k];\n    if (typeof next !== 'object' || next === null) cur[k] = {};\n    cur = cur[k] as Record<string, unknown>;\n  }\n  cur[keys[keys.length - 1]] = value;\n}\n\nexport const transformerBot: Transformer.Init<\n  Transformer.Types<BotSettings>\n> = (context) => {\n  const { config } = context;\n  const settings: BotSettings = config.settings ?? {};\n  const input: Required<BotInput> = {\n    ...DEFAULT_INPUT,\n    ...(settings.input ?? {}),\n  };\n  const output: BotOutput = {\n    ...DEFAULT_OUTPUT,\n    ...(settings.output ?? {}),\n  };\n\n  return {\n    // Init's input config type is Partial<Settings>; the instance config type\n    // is Settings. Same cast pattern the fingerprint transformer uses.\n    type: 'bot',\n    config: config as Transformer.Config<Transformer.Types<BotSettings>>,\n\n    async push(event, ctx) {\n      const { ingest, collector } = ctx;\n      const source = { event, ingest };\n\n      // v1 only reads userAgent. Other input fields are reserved for v1.1\n      // (header heuristics); resolved-but-unused here would be wasteful, so\n      // they are intentionally not read yet.\n      const uaValue = await getMappingValue(source, input.userAgent, {\n        collector,\n      });\n      const ua = typeof uaValue === 'string' ? uaValue : '';\n      const score = computeScore(ua);\n\n      let nextEvent = event;\n\n      const writeOutput = (path: string, value: unknown) => {\n        if (!path || value === undefined) return;\n        if (path.startsWith('ingest.')) {\n          setNestedPath(ingest, path.slice('ingest.'.length), value);\n        } else {\n          nextEvent = setByPath(nextEvent, path, value);\n        }\n      };\n\n      writeOutput(output.botScore ?? '', score.botScore);\n      writeOutput(output.agentScore ?? '', score.agentScore);\n      writeOutput(output.agentProduct ?? '', score.agentProduct);\n\n      return { event: nextEvent };\n    },\n  };\n};\n","import { isbot } from 'isbot';\nimport { agents, type AgentEntry } from '../data/agents';\n\nexport interface UAResult {\n  isBot: boolean;\n  agent?: { product: string; purpose: AgentEntry['purpose'] };\n}\n\nexport function detectUA(ua: string): UAResult {\n  const lower = ua.toLowerCase();\n  const matched = agents.find((a) => lower.includes(a.match.toLowerCase()));\n  return {\n    isBot: !ua || isbot(ua) || matched !== undefined,\n    agent: matched\n      ? { product: matched.product, purpose: matched.purpose }\n      : undefined,\n  };\n}\n","/**\n * Curated AI agent UA-substring map (2026-Q2).\n *\n * Each entry: substring matched case-insensitively against the User-Agent,\n * a product label written to event.user.agentProduct, and the purpose category.\n *\n * Purpose semantics:\n *   - 'training'     — crawls for model training; usually filter from analytics\n *   - 'search-index' — crawls to power AI search answers; AEO-relevant\n *   - 'user-action'  — fetch initiated by a human via an AI tool; often kept as traffic\n *\n * Order matters: first-hit wins. More-specific entries must precede broader ones.\n *\n * Vendor docs of record (verified 2026-05):\n *   OpenAI:        https://platform.openai.com/docs/bots\n *   Anthropic:     https://support.claude.com/en/articles/8896518\n *   Perplexity:    https://docs.perplexity.ai/guides/bots\n *   Meta:          https://developers.facebook.com/docs/sharing/webmasters/web-crawlers\n *   Google:        https://developers.google.com/search/docs/crawling-indexing/google-common-crawlers\n *   Apple:         https://support.apple.com/en-us/119829\n *   DuckDuckGo:    https://duckduckgo.com/duckduckbot\n *   Common Crawl:  https://commoncrawl.org/faq\n *   Amazon:        https://developer.amazon.com/amazonbot\n *\n * Community cross-reference: https://github.com/ai-robots-txt/ai.robots.txt\n *\n * Reviewed quarterly — see /workspaces/developer/docs/research/2026-05-13-bot-detection.md.\n */\nexport interface AgentEntry {\n  match: string;\n  product: string;\n  purpose: 'training' | 'search-index' | 'user-action';\n}\n\nexport const agents: AgentEntry[] = [\n  // --- OpenAI ---\n  { match: 'ChatGPT-User', product: 'ChatGPT-User', purpose: 'user-action' },\n  { match: 'ChatGPT-Agent', product: 'ChatGPT-Agent', purpose: 'user-action' },\n  { match: 'OAI-SearchBot', product: 'OAI-SearchBot', purpose: 'search-index' },\n  { match: 'GPTBot', product: 'GPTBot', purpose: 'training' },\n\n  // --- Anthropic ---\n  // Claude-SearchBot must precede Claude-User (defensive specificity for composite UAs)\n  {\n    match: 'Claude-SearchBot',\n    product: 'Claude-SearchBot',\n    purpose: 'search-index',\n  },\n  { match: 'Claude-User', product: 'Claude-User', purpose: 'user-action' },\n  { match: 'Claude-Code', product: 'Claude-Code', purpose: 'user-action' },\n  { match: 'ClaudeBot', product: 'ClaudeBot', purpose: 'training' },\n  // Legacy: only used by older Anthropic crawlers; kept for back-compat with old logs.\n  { match: 'anthropic-ai', product: 'anthropic-ai', purpose: 'training' },\n\n  // --- Perplexity ---\n  {\n    match: 'Perplexity-User',\n    product: 'Perplexity-User',\n    purpose: 'user-action',\n  },\n  {\n    match: 'PerplexityBot',\n    product: 'PerplexityBot',\n    purpose: 'search-index',\n  },\n\n  // --- Mistral ---\n  {\n    match: 'MistralAI-User',\n    product: 'MistralAI-User',\n    purpose: 'user-action',\n  },\n\n  // --- Meta ---\n  {\n    match: 'Meta-ExternalFetcher',\n    product: 'Meta-ExternalFetcher',\n    purpose: 'user-action',\n  },\n  {\n    match: 'Meta-ExternalAgent',\n    product: 'Meta-ExternalAgent',\n    purpose: 'training',\n  },\n\n  // --- Google ---\n  {\n    match: 'Google-CloudVertexBot',\n    product: 'Google-CloudVertexBot',\n    purpose: 'training',\n  },\n  {\n    match: 'Google-Extended',\n    product: 'Google-Extended',\n    purpose: 'training',\n  },\n\n  // --- Apple ---\n  {\n    match: 'Applebot-Extended',\n    product: 'Applebot-Extended',\n    purpose: 'training',\n  },\n\n  // --- Amazon ---\n  { match: 'Amazonbot', product: 'Amazonbot', purpose: 'training' },\n\n  // --- DuckDuckGo ---\n  {\n    match: 'DuckAssistBot',\n    product: 'DuckAssistBot',\n    purpose: 'user-action',\n  },\n\n  // --- ByteDance ---\n  { match: 'Bytespider', product: 'Bytespider', purpose: 'training' },\n\n  // --- Common Crawl ---\n  { match: 'CCBot', product: 'CCBot', purpose: 'training' },\n];\n","import { detectUA } from './ua';\n\nexport interface ScoreResult {\n  /** 0-99, higher = more bot. v1 emits discrete values: 0, 70, 80, 90, 95. */\n  botScore: number;\n  /**\n   * 0-99, higher = more likely an AI agent. v1 emits only 0 or 95\n   * (binary UA-map match). Graduated values (e.g. 70 for unverified UA\n   * claim, 99 for IP-reverse-DNS verified) are planned for v1.1.\n   */\n  agentScore: number;\n  /** Matched AI agent UA substring, when one was found. */\n  agentProduct?: string;\n}\n\n/**\n * v1: UA-only.\n *\n * botScore baseline:\n *   - Empty UA            → 70 (real browsers rarely strip UA)\n *   - AI training crawler → 95\n *   - AI user-action      → 90\n *   - isbot true          → 80\n *   - Otherwise           → 0\n *\n * Header heuristics (Sec-Fetch missing, Sec-CH-UA major mismatch,\n * Accept-Language stripping) are intentionally deferred to v1.1 —\n * see the README \"Not in v1\" section and the research file.\n */\nexport function computeScore(ua: string): ScoreResult {\n  if (!ua) {\n    return { botScore: 70, agentScore: 0, agentProduct: undefined };\n  }\n\n  const uaResult = detectUA(ua);\n\n  let botScore = 0;\n  if (uaResult.agent) {\n    botScore = uaResult.agent.purpose === 'user-action' ? 90 : 95;\n  } else if (uaResult.isBot) {\n    botScore = 80;\n  }\n\n  return {\n    botScore,\n    agentScore: uaResult.agent ? 95 : 0,\n    agentProduct: uaResult.agent?.product,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/walkerOS.json

@@ -0,0 +1,557 @@
+{
+  "$meta": {
+    "package": "@walkeros/server-transformer-bot",
+    "version": "4.1.0",
+    "type": "transformer",
+    "platform": [
+      "server"
+    ],
+    "docs": "https://www.walkeros.io/docs/transformers/bot",
+    "source": "https://github.com/elbwalker/walkerOS/tree/main/packages/server/transformers/bot/src"
+  },
+  "schemas": {
+    "settings": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "properties": {
+        "input": {
+          "description": "Input signal sources, resolved via getMappingValue against { event, ingest }. v1 only reads userAgent; other fields reserved for v1.1 header heuristics.",
+          "type": "object",
+          "properties": {
+            "userAgent": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "ip": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "acceptLanguage": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "acceptEncoding": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "secFetchSite": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "secFetchMode": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "secFetchDest": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "secFetchUser": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "secChUa": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "secChUaMobile": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            },
+            "secChUaPlatform": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "description": "Dot-notation path like \"ingest.userAgent\""
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {},
+                    "fn": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Mapping value object"
+                }
+              ]
+            }
+          },
+          "additionalProperties": false,
+          "title": "input"
+        },
+        "output": {
+          "description": "Output paths for bot/agent annotations.",
+          "type": "object",
+          "properties": {
+            "botScore": {
+              "description": "Path for bot score (0-99, higher = more bot). Default: \"user.botScore\". Use \"ingest.*\" to route to pipeline scratch instead of the event. Empty string or omit = skip.",
+              "type": "string"
+            },
+            "agentScore": {
+              "description": "Path for AI agent score (0-99). v1 emits 0 (no match) or 95 (UA-map match). Default: \"user.agentScore\".",
+              "type": "string"
+            },
+            "agentProduct": {
+              "description": "Path for matched UA substring (e.g. \"ChatGPT-User\"). Off by default — set to enable.",
+              "type": "string"
+            }
+          },
+          "additionalProperties": false,
+          "title": "output"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Bot detection transformer: annotates events with bot and AI-agent scores."
+    }
+  },
+  "examples": {
+    "step": {
+      "chatgptUserAgent": {
+        "title": "ChatGPT-User (user-action AI)",
+        "description": "A real human routed an AI to fetch this page. botScore high but lower than crawlers — agentProduct lets destinations keep this traffic.",
+        "in": {
+          "name": "page view",
+          "data": {
+            "title": "Home",
+            "id": "/"
+          },
+          "id": "ev-1700000602",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000600,
+          "source": {
+            "type": "express",
+            "platform": "server"
+          }
+        },
+        "out": [
+          [
+            "return",
+            {
+              "event": {
+                "name": "page view",
+                "data": {
+                  "title": "Home",
+                  "id": "/"
+                },
+                "id": "ev-1700000602",
+                "trigger": "load",
+                "entity": "page",
+                "action": "view",
+                "timestamp": 1700000600,
+                "source": {
+                  "type": "express",
+                  "platform": "server"
+                },
+                "user": {
+                  "botScore": 90,
+                  "agentScore": 95
+                }
+              }
+            }
+          ]
+        ]
+      },
+      "curlClient": {
+        "public": false,
+        "description": "curl client — caught by isbot. agentScore zero.",
+        "in": {
+          "name": "page view",
+          "data": {
+            "title": "Home",
+            "id": "/"
+          },
+          "id": "ev-1700000603",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000600,
+          "source": {
+            "type": "express",
+            "platform": "server"
+          }
+        },
+        "out": [
+          [
+            "return",
+            {
+              "event": {
+                "name": "page view",
+                "data": {
+                  "title": "Home",
+                  "id": "/"
+                },
+                "id": "ev-1700000603",
+                "trigger": "load",
+                "entity": "page",
+                "action": "view",
+                "timestamp": 1700000600,
+                "source": {
+                  "type": "express",
+                  "platform": "server"
+                },
+                "user": {
+                  "botScore": 80,
+                  "agentScore": 0
+                }
+              }
+            }
+          ]
+        ]
+      },
+      "gptBotCrawler": {
+        "title": "GPTBot training crawler",
+        "description": "OpenAI training crawler. Both botScore and agentScore are high.",
+        "in": {
+          "name": "page view",
+          "data": {
+            "title": "Home",
+            "id": "/"
+          },
+          "id": "ev-1700000601",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000600,
+          "source": {
+            "type": "express",
+            "platform": "server"
+          }
+        },
+        "out": [
+          [
+            "return",
+            {
+              "event": {
+                "name": "page view",
+                "data": {
+                  "title": "Home",
+                  "id": "/"
+                },
+                "id": "ev-1700000601",
+                "trigger": "load",
+                "entity": "page",
+                "action": "view",
+                "timestamp": 1700000600,
+                "source": {
+                  "type": "express",
+                  "platform": "server"
+                },
+                "user": {
+                  "botScore": 95,
+                  "agentScore": 95
+                }
+              }
+            }
+          ]
+        ]
+      },
+      "humanChrome": {
+        "title": "Human visitor (Chrome)",
+        "description": "Modern Chrome UA. No bot or agent signals.",
+        "in": {
+          "name": "page view",
+          "data": {
+            "title": "Home",
+            "id": "/"
+          },
+          "id": "ev-1700000600",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000600,
+          "source": {
+            "type": "express",
+            "platform": "server"
+          }
+        },
+        "out": [
+          [
+            "return",
+            {
+              "event": {
+                "name": "page view",
+                "data": {
+                  "title": "Home",
+                  "id": "/"
+                },
+                "id": "ev-1700000600",
+                "trigger": "load",
+                "entity": "page",
+                "action": "view",
+                "timestamp": 1700000600,
+                "source": {
+                  "type": "express",
+                  "platform": "server"
+                },
+                "user": {
+                  "botScore": 0,
+                  "agentScore": 0
+                }
+              }
+            }
+          ]
+        ]
+      },
+      "missingUA": {
+        "public": false,
+        "description": "No User-Agent — baseline 70 (UA stripping is overwhelmingly bots or hardened privacy tools).",
+        "in": {
+          "name": "page view",
+          "data": {
+            "title": "Home",
+            "id": "/"
+          },
+          "id": "ev-1700000604",
+          "trigger": "load",
+          "entity": "page",
+          "action": "view",
+          "timestamp": 1700000600,
+          "source": {
+            "type": "express",
+            "platform": "server"
+          }
+        },
+        "out": [
+          [
+            "return",
+            {
+              "event": {
+                "name": "page view",
+                "data": {
+                  "title": "Home",
+                  "id": "/"
+                },
+                "id": "ev-1700000604",
+                "trigger": "load",
+                "entity": "page",
+                "action": "view",
+                "timestamp": 1700000600,
+                "source": {
+                  "type": "express",
+                  "platform": "server"
+                },
+                "user": {
+                  "botScore": 70,
+                  "agentScore": 0
+                }
+              }
+            }
+          ]
+        ]
+      }
+    }
+  },
+  "hints": {
+    "ingest-prerequisite": {
+      "text": "The bot transformer reads userAgent from ctx.ingest (path \"ingest.userAgent\" by default). The upstream server source must populate it via config.ingest mapping, otherwise the UA is empty and every event scores 70 (baseline for missing UA).",
+      "code": [
+        {
+          "lang": "json",
+          "code": "{\n  \"sources\": {\n    \"express\": {\n      \"package\": \"@walkeros/server-source-express\",\n      \"config\": {\n        \"ingest\": {\n          \"userAgent\": \"req.headers.user-agent\"\n        }\n      }\n    }\n  },\n  \"transformers\": {\n    \"bot\": {\n      \"package\": \"@walkeros/server-transformer-bot\"\n    }\n  }\n}"
+        }
+      ]
+    },
+    "output-routing": {
+      "text": "Outputs default to event.user.botScore and event.user.agentScore. Redirect to ingest.* to keep the analytics event clean while still routing on the score downstream. Empty string (or omit) skips writing that field entirely. agentProduct is off by default — set it to enable writing the matched UA substring.",
+      "code": [
+        {
+          "lang": "json",
+          "code": "{\n  \"transformers\": {\n    \"bot\": {\n      \"package\": \"@walkeros/server-transformer-bot\",\n      \"config\": {\n        \"settings\": {\n          \"output\": {\n            \"botScore\": \"ingest.bot.score\",\n            \"agentScore\": \"ingest.bot.agent\",\n            \"agentProduct\": \"user.agentProduct\"\n          }\n        }\n      }\n    }\n  }\n}"
+        }
+      ]
+    },
+    "destination-filtering": {
+      "text": "Recommended destination-mapping recipes. Drop all bots: botScore > 50. Drop crawlers but keep user-action AI traffic: botScore > 50 AND agentProduct NOT LIKE \"%-User\". AI traffic report: group by agentProduct WHERE agentScore > 50. The transformer never drops events — filtering is always a destination decision."
+    },
+    "detection-scope": {
+      "text": "v1 is UA-only: wraps isbot (curl, wget, headless Chrome defaults, well-known crawlers) plus a curated AI-agent UA map (OpenAI, Anthropic, Perplexity, Mistral, Meta, Google, Apple, Amazon, DuckDuckGo, ByteDance, Common Crawl). It will NOT catch: residential-proxy + stealth Chrome + realistic behavior; reverse-DNS-verified search engines; client-side runtime tells. v1.1 adds header consistency heuristics (Sec-Fetch, Sec-CH-UA, Accept-Language) with proper GREASE handling. For commercial-grade detection use Cloudflare Bot Management, DataDome, or HUMAN."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@walkeros/server-transformer-bot",
+  "description": "Server-side bot and AI-agent detection transformer for walkerOS",
+  "version": "4.1.0",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./walkerOS.json": "./dist/walkerOS.json"
+  },
+  "files": [
+    "dist/**",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup --silent",
+    "clean": "rm -rf .turbo && rm -rf dist",
+    "dev": "jest --watchAll --colors",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"**/*.ts*\"",
+    "test": "jest",
+    "update": "npx npm-check-updates -u && npm update"
+  },
+  "dependencies": {
+    "@walkeros/core": "4.1.0",
+    "isbot": "^5.1.39"
+  },
+  "devDependencies": {
+    "@walkeros/core": "4.1.0"
+  },
+  "repository": {
+    "url": "git+https://github.com/elbwalker/walkerOS.git",
+    "directory": "packages/server/transformers/bot"
+  },
+  "author": "elbwalker <hello@elbwalker.com>",
+  "homepage": "https://github.com/elbwalker/walkerOS#readme",
+  "bugs": {
+    "url": "https://github.com/elbwalker/walkerOS/issues"
+  },
+  "walkerOS": {
+    "type": "transformer",
+    "platform": [
+      "server"
+    ],
+    "docs": "https://www.walkeros.io/docs/transformers/bot"
+  },
+  "keywords": [
+    "walkerOS",
+    "walkerOS-transformer",
+    "transformer",
+    "bot",
+    "bot-detection",
+    "ai-agent"
+  ],
+  "funding": [
+    {
+      "type": "GitHub Sponsors",
+      "url": "https://github.com/sponsors/elbwalker"
+    }
+  ]
+}