@adwait12345/telemetry-core

The shared core of the Telemetry SDK. Contains bot detection logic, the send function with retry support, and all shared TypeScript types used by the framework adapters (telemetry-next, telemetry-express, telemetry-astro).

You typically do not install this directly — install the adapter for your framework instead. Use this package if you are building a custom adapter.

Installation

npm install @adwait12345/telemetry-core
# or
pnpm add @adwait12345/telemetry-core

What's included

detectBot(req, customBots?)

Runs multi-layer bot detection against a normalized request object.

Detection layers (in priority order):

| Layer | Method | Confidence | |-------|--------|------------| | 1 | Automation headers (x-selenium, x-puppeteer, x-playwright, etc.) | certain | | 2 | HTTP/1.0 — no modern browser uses this | high | | 3 | Named bot UA match (100+ known bots across 16 categories) | certain | | 4 | Generic bot UA patterns (/bot/i, /crawler/i, empty/short UA, etc.) | high | | 5 | Header anomaly — claims modern browser but missing sec-fetch-site / accept-language | medium–high |

import { detectBot } from "@adwait12345/telemetry-core";

const result = detectBot({
  userAgent: "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
  ip: "66.249.66.1",
  path: "/",
  method: "GET",
  referrer: null,
  acceptLanguage: null,
  acceptEncoding: "gzip",
  secFetchSite: null,
  httpVersion: "1.1",
  automationHeaders: [],
});

// result.isBot        → true
// result.botName      → "Googlebot"
// result.botCategory  → "search"
// result.confidence   → "certain"
// result.method       → "ua-match"

extractAutomationHeaders(headers)

Checks a plain headers object for known automation tool headers. Returns the list of matched header names. Call this before detectBot to populate automationHeaders.

import { extractAutomationHeaders } from "@adwait12345/telemetry-core";

const matched = extractAutomationHeaders(req.headers);
// e.g. ["x-playwright"] if Playwright is driving the browser

sendToTelemetry(payload, config)

Sends a tracking payload to the Telemetry API. Includes:

• 3 attempts with exponential backoff (200 ms → 400 ms)
• 5 second timeout per attempt via AbortController
• 4xx errors skip retry (they will not succeed on retry)
• Automatic Authorization: Bearer {serverSecret} header

import { sendToTelemetry } from "@adwait12345/telemetry-core";

await sendToTelemetry(payload, {
  projectId: "your-project-id",
  apiUrl: "https://telemetry-uqd3.onrender.com",
  serverSecret: "sk_...",
});

Bot categories

The 100+ built-in bots are organized into 16 categories:

| Category | Examples | |----------|---------| | ai-crawler | GPTBot, ClaudeBot, PerplexityBot, Applebot | | ai-assistant | ChatGPT-User, Claude-Web, Copilot | | search | Googlebot, Bingbot, DuckDuckBot, Yandex | | seo | AhrefsBot, SemrushBot, MajesticSEO | | advertising | Mediapartners-Google, AdsBot-Google | | monitor | UptimeRobot, Pingdom, StatusCake | | preview | Slackbot, Twitterbot, facebookexternalhit | | webhook | Stripe-Webhook, GitHub-Hookshot, Shopify | | feed | Feedly, Inoreader, NewsBlur | | ecommerce | Shopify, Wix | | verification | Let's Encrypt, SSL Labs | | analytics | New Relic, Datadog | | social | LinkedInBot, Pinterest | | accessibility | ChromeVox | | scraper | Scrapy, HTTrack | | unknown | Anything matching generic bot patterns |

TelemetryConfig reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectId | string | required | Your Telemetry project ID | | apiUrl | string | hosted service | API base URL | | serverSecret | string | — | Secret key for server-side auth (Bearer {serverSecret}) | | authorizationHeader | string | — | Fully custom Authorization header value, overrides serverSecret | | headers | Record<string, string> | — | Extra headers merged into every telemetry request | | trackAll | boolean | false | Track all requests, not just bots | | trackSearchBots | boolean | true | Include Googlebot, Bingbot etc. | | ignorePaths | (string \| RegExp)[] | — | Paths to skip (exact strings or regex) | | customBots | Array<{name, pattern, category?}> | — | Add your own bot definitions | | debug | boolean | false | Enable verbose console logging |