{"_id":"@awasero/citela","name":"@awasero/citela","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@awasero/citela","version":"0.1.0","description":"Google Search Console for AI answers. Know when GPTBot, ClaudeBot, PerplexityBot & friends read your site — one command. npx @awasero/citela init","keywords":["ai","gptbot","claudebot","perplexity","crawler","geo","aeo","ai-visibility","nextjs","middleware","llm"],"license":"MIT","author":{"name":"Awasero"},"homepage":"https://citela.com","repository":{"type":"git","url":"git+https://github.com/awasero/citela.git","directory":"packages/citela"},"type":"module","bin":{"citela":"dist/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./local":{"types":"./dist/local.d.ts","import":"./dist/local.js","require":"./dist/local.cjs"}},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=18"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","lint":"tsc --noEmit","test":"node --test","size":"node scripts/check-size.mjs","clean":"rm -rf dist .turbo"},"devDependencies":{"@citela/shared":"workspace:*","tsup":"^8.3.5","typescript":"^5.7.3"},"_id":"@awasero/citela@0.1.0","gitHead":"223a07f3744f50d3ee3ceef3fdf158216710cfe5","bugs":{"url":"https://github.com/awasero/citela/issues"},"_nodeVersion":"23.4.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-U3yGTWNravuHkWxVqMhQa1zTt8jjyzIdji6jayJBxG5zVvBNZS95dikVTbZgkTnHuIppV5xLF52ABkUiRjI3qQ==","shasum":"c48d5c24db65b3ec272cabb5faeac3ea9c9c468b","tarball":"https://registry.npmjs.org/@awasero/citela/-/citela-0.1.0.tgz","fileCount":19,"unpackedSize":185260,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDqQiE4o/i0k0NSq6vxjm/lSJsmpl0GZEeCQHyRv18srAiBNv5YPCTkhPVrYYMJeTG/R2cshL2H6wjBv24dsrwut6g=="}]},"_npmUser":{"name":"awasero","email":"carlos@awasero.com"},"directories":{},"maintainers":[{"name":"awasero","email":"carlos@awasero.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/citela_0.1.0_1784129192028_0.8593933990295073"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-15T15:26:31.882Z","0.1.0":"2026-07-15T15:26:32.155Z","modified":"2026-07-15T15:26:32.347Z"},"maintainers":[{"name":"awasero","email":"carlos@awasero.com"}],"description":"Google Search Console for AI answers. Know when GPTBot, ClaudeBot, PerplexityBot & friends read your site — one command. npx @awasero/citela init","homepage":"https://citela.com","keywords":["ai","gptbot","claudebot","perplexity","crawler","geo","aeo","ai-visibility","nextjs","middleware","llm"],"repository":{"type":"git","url":"git+https://github.com/awasero/citela.git","directory":"packages/citela"},"author":{"name":"Awasero"},"bugs":{"url":"https://github.com/awasero/citela/issues"},"license":"MIT","readme":"# @awasero/citela\n\n**Google Search Console for AI answers.** Know when AI crawlers — GPTBot, ClaudeBot, PerplexityBot, Google-Extended and friends — read your site. One command.\n\n```bash\nnpx @awasero/citela init\n# ✓ Listening for AI crawlers.\n```\n\nThen watch them arrive:\n\n```bash\nnpx @awasero/citela report\n\n  Citela — AI crawler activity  (last 7 days)\n\n  Verified crawls by bot\n       12  GPTBot (openai, crawler)\n        4  PerplexityBot (perplexity, crawler)\n        3  ClaudeBot (anthropic, crawler)\n\n  Most-read pages\n        9  /pricing\n        6  /docs\n```\n\n## Why\n\nIf ChatGPT, Claude, or Perplexity never read your site, they can't recommend your product. Client-side analytics can't tell you — **AI bots don't run JavaScript**. Detection has to happen server-side, in middleware. That's what this is.\n\nIt works **standalone, with no account**: a local ring buffer records verified crawler hits and `citela report` prints them. Connect an API key to stream events to [Citela](https://citela.com) for real-time alerts (\"GPTBot read your /pricing 4 minutes ago\"), answer tracking, and one-command fixes your coding agent can ship.\n\n## Install\n\n```bash\nnpx @awasero/citela init            # standalone\nnpx @awasero/citela init --api-key <key>   # connected: streaming + real-time alerts\n```\n\n`init` is **non-interactive and idempotent** — safe to run from a coding agent, safe to re-run. It:\n\n- writes (or wires into) your `middleware.ts`\n- installs a tiny local sink route (`app/api/_citela`) for standalone mode\n- adds `.citela/` to your `.gitignore`\n\nSupports **Next.js** (App & Pages Router) today. Express / Astro / SvelteKit adapters are on the roadmap.\n\n## What it detects\n\nA maintained registry of AI crawlers and on-demand fetchers, with anti-spoof **IP verification** against published vendor ranges. User-agents are trivially spoofable, so unverified hits are recorded but **excluded from headline counts** — a number you can trust.\n\nDetected: GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, PerplexityBot, Perplexity-User, Google-Extended, GoogleOther, Bingbot, Meta-ExternalAgent, Amazonbot, Applebot-Extended, Bytespider, CCBot — refreshed regularly when connected.\n\n## Safety\n\nThe sensor is built to be invisible to your app:\n\n- **Total try/catch** — no exception can escape into your request path.\n- **< 1ms p99 overhead** — user-agent match then a fire-and-forget send; no inline network calls.\n- **< 20KB, zero runtime dependencies.**\n- **Never logs human visitor data.** Only matched *bot* hits are recorded — the bot, the path, the timestamp. Nothing about your human visitors.\n\n## Manual wiring\n\n`init` writes this for you, but if you manage your own middleware:\n\n```ts\nimport { NextResponse } from 'next/server';\nimport { collect, CITELA_MATCHER } from '@awasero/citela';\n\nexport function middleware(request, event) {\n  collect(request, event); // fire-and-forget; never throws\n  return NextResponse.next();\n}\n\nexport const config = { matcher: CITELA_MATCHER };\n```\n\n## Telemetry\n\n`init` sends an **anonymous, opt-out** install ping: a random install id, the framework, and whether an agent ran it. **No site data, no visitor data.** Disable with `CITELA_TELEMETRY=0` or `DO_NOT_TRACK=1`.\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `citela init [--api-key <key>] [--agent] [--dir <path>] [--json]` | Install the sensor |\n| `citela report [--days <n>] [--json]` | Print recent AI-crawler activity |\n| `citela help` | Show help |\n\n## License\n\nMIT © Awasero\n","readmeFilename":"README.md","_rev":"1-e38e4bca70fc2ca530ce68951ad66da9"}