@adwait12345/telemetry-core 0.1.3 → 0.1.4

package/README.md

@@ -0,0 +1,127 @@
+# `@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
+
+```bash
+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` |
+
+```typescript
+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`.
+
+```typescript
+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
+
+```typescript
+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 |

package/dist/index.js

@@ -1151,7 +1151,9 @@ async function sendWithRetry(endpoint, payload, config, retries = 2) {
       clearTimeout(timeout);
       if (config.debug) {
         if (error?.name === "AbortError") {
-          console.error(`[Telemetry] Attempt ${attempt + 1} timed out after 5s.`);
+          console.error(
+            `[Telemetry] Attempt ${attempt + 1} timed out after 5s.`
+          );
         } else {
           console.error(`[Telemetry] Attempt ${attempt + 1} error:`, error);
         }
@@ -1168,7 +1170,9 @@ async function sendWithRetry(endpoint, payload, config, retries = 2) {
 async function sendToTelemetry(payload, config) {
   if (!config.apiUrl) {
     if (config.debug) {
-      console.warn("[Telemetry] No apiUrl configured \u2014 skipping telemetry send.");
+      console.warn(
+        "[Telemetry] No apiUrl configured \u2014 skipping telemetry send."
+      );
     }
     return;
   }

package/dist/index.mjs

@@ -1107,7 +1107,9 @@ async function sendWithRetry(endpoint, payload, config, retries = 2) {
       clearTimeout(timeout);
       if (config.debug) {
         if (error?.name === "AbortError") {
-          console.error(`[Telemetry] Attempt ${attempt + 1} timed out after 5s.`);
+          console.error(
+            `[Telemetry] Attempt ${attempt + 1} timed out after 5s.`
+          );
         } else {
           console.error(`[Telemetry] Attempt ${attempt + 1} error:`, error);
         }
@@ -1124,7 +1126,9 @@ async function sendWithRetry(endpoint, payload, config, retries = 2) {
 async function sendToTelemetry(payload, config) {
   if (!config.apiUrl) {
     if (config.debug) {
-      console.warn("[Telemetry] No apiUrl configured \u2014 skipping telemetry send.");
+      console.warn(
+        "[Telemetry] No apiUrl configured \u2014 skipping telemetry send."
+      );
     }
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adwait12345/telemetry-core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Framework-agnostic core for Telemetry SDK — bot detection and server-side tracking",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -13,7 +13,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "devDependencies": {
     "tsup": "^8.0.0",