@adwait12345/telemetry-core 0.1.2 → 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.d.mts

@@ -65,6 +65,18 @@ interface TelemetryConfig {
      * This is required since these requests originate from the server and cannot pass domain validation checks via Origin.
      */
     serverSecret?: string;
+    /**
+     * Fully custom Authorization header value.
+     * Overrides the default "Bearer {serverSecret}" format.
+     * e.g. "Token mytoken" or "Basic dXNlcjpwYXNz"
+     */
+    authorizationHeader?: string;
+    /**
+     * Additional custom headers to send with every telemetry request.
+     * These are merged on top of the defaults and can override them.
+     * e.g. { "x-workspace-id": "abc123" }
+     */
+    headers?: Record<string, string>;
 }
 /** Payload sent to the Telemetry server-side tracking endpoint */
 interface ServerTrackPayload {
@@ -142,7 +154,7 @@ declare const ALL_BOTS: BotDefinition[];
 
 /**
  * Sends a server-side payload to the Telemetry backend.
- * This is meant to be fire-and-forget, so it does not throw errors.
+ * Automatically retries on transient failures with exponential backoff.
  *
  * @param payload The data to track.
  * @param config The Telemetry configuration.

package/dist/index.d.ts

@@ -65,6 +65,18 @@ interface TelemetryConfig {
      * This is required since these requests originate from the server and cannot pass domain validation checks via Origin.
      */
     serverSecret?: string;
+    /**
+     * Fully custom Authorization header value.
+     * Overrides the default "Bearer {serverSecret}" format.
+     * e.g. "Token mytoken" or "Basic dXNlcjpwYXNz"
+     */
+    authorizationHeader?: string;
+    /**
+     * Additional custom headers to send with every telemetry request.
+     * These are merged on top of the defaults and can override them.
+     * e.g. { "x-workspace-id": "abc123" }
+     */
+    headers?: Record<string, string>;
 }
 /** Payload sent to the Telemetry server-side tracking endpoint */
 interface ServerTrackPayload {
@@ -142,7 +154,7 @@ declare const ALL_BOTS: BotDefinition[];
 
 /**
  * Sends a server-side payload to the Telemetry backend.
- * This is meant to be fire-and-forget, so it does not throw errors.
+ * Automatically retries on transient failures with exponential backoff.
  *
  * @param payload The data to track.
  * @param config The Telemetry configuration.

package/dist/index.js

@@ -1112,10 +1112,67 @@ function extractAutomationHeaders(headers) {
 }
 
 // src/index.ts
+function buildHeaders(config) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (config.authorizationHeader) {
+    headers["Authorization"] = config.authorizationHeader;
+  } else if (config.serverSecret) {
+    headers["Authorization"] = `Bearer ${config.serverSecret}`;
+  }
+  if (config.headers) {
+    Object.assign(headers, config.headers);
+  }
+  return headers;
+}
+async function sendWithRetry(endpoint, payload, config, retries = 2) {
+  const headers = buildHeaders(config);
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5e3);
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+      if (response.ok) return;
+      if (config.debug) {
+        const text = await response.text();
+        console.error(
+          `[Telemetry] Attempt ${attempt + 1} failed: ${response.status} \u2014 ${text}`
+        );
+      }
+      if (response.status >= 400 && response.status < 500) return;
+    } catch (error) {
+      clearTimeout(timeout);
+      if (config.debug) {
+        if (error?.name === "AbortError") {
+          console.error(
+            `[Telemetry] Attempt ${attempt + 1} timed out after 5s.`
+          );
+        } else {
+          console.error(`[Telemetry] Attempt ${attempt + 1} error:`, error);
+        }
+      }
+    }
+    if (attempt < retries) {
+      await new Promise((r) => setTimeout(r, 200 * Math.pow(2, attempt)));
+    }
+  }
+  if (config.debug) {
+    console.error("[Telemetry] All retry attempts failed \u2014 giving up.");
+  }
+}
 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;
   }
@@ -1123,34 +1180,7 @@ async function sendToTelemetry(payload, config) {
   if (config.debug) {
     console.log(`[Telemetry] Sending payload to ${endpoint}`, payload);
   }
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 3e3);
-  try {
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${config.serverSecret}`
-      },
-      body: JSON.stringify(payload),
-      signal: controller.signal
-    });
-    if (!response.ok && config.debug) {
-      console.error(`[Telemetry] Failed to send payload: ${response.status} ${response.statusText}`);
-      const text = await response.text();
-      console.error(`[Telemetry] Response body:`, text);
-    }
-  } catch (error) {
-    if (config.debug) {
-      if (error?.name === "AbortError") {
-        console.error("[Telemetry] Request timed out after 3s \u2014 skipping.");
-      } else {
-        console.error("[Telemetry] Error sending payload:", error);
-      }
-    }
-  } finally {
-    clearTimeout(timeout);
-  }
+  await sendWithRetry(endpoint, payload, config);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1068,10 +1068,67 @@ function extractAutomationHeaders(headers) {
 }
 
 // src/index.ts
+function buildHeaders(config) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (config.authorizationHeader) {
+    headers["Authorization"] = config.authorizationHeader;
+  } else if (config.serverSecret) {
+    headers["Authorization"] = `Bearer ${config.serverSecret}`;
+  }
+  if (config.headers) {
+    Object.assign(headers, config.headers);
+  }
+  return headers;
+}
+async function sendWithRetry(endpoint, payload, config, retries = 2) {
+  const headers = buildHeaders(config);
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5e3);
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+      if (response.ok) return;
+      if (config.debug) {
+        const text = await response.text();
+        console.error(
+          `[Telemetry] Attempt ${attempt + 1} failed: ${response.status} \u2014 ${text}`
+        );
+      }
+      if (response.status >= 400 && response.status < 500) return;
+    } catch (error) {
+      clearTimeout(timeout);
+      if (config.debug) {
+        if (error?.name === "AbortError") {
+          console.error(
+            `[Telemetry] Attempt ${attempt + 1} timed out after 5s.`
+          );
+        } else {
+          console.error(`[Telemetry] Attempt ${attempt + 1} error:`, error);
+        }
+      }
+    }
+    if (attempt < retries) {
+      await new Promise((r) => setTimeout(r, 200 * Math.pow(2, attempt)));
+    }
+  }
+  if (config.debug) {
+    console.error("[Telemetry] All retry attempts failed \u2014 giving up.");
+  }
+}
 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;
   }
@@ -1079,34 +1136,7 @@ async function sendToTelemetry(payload, config) {
   if (config.debug) {
     console.log(`[Telemetry] Sending payload to ${endpoint}`, payload);
   }
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 3e3);
-  try {
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${config.serverSecret}`
-      },
-      body: JSON.stringify(payload),
-      signal: controller.signal
-    });
-    if (!response.ok && config.debug) {
-      console.error(`[Telemetry] Failed to send payload: ${response.status} ${response.statusText}`);
-      const text = await response.text();
-      console.error(`[Telemetry] Response body:`, text);
-    }
-  } catch (error) {
-    if (config.debug) {
-      if (error?.name === "AbortError") {
-        console.error("[Telemetry] Request timed out after 3s \u2014 skipping.");
-      } else {
-        console.error("[Telemetry] Error sending payload:", error);
-      }
-    }
-  } finally {
-    clearTimeout(timeout);
-  }
+  await sendWithRetry(endpoint, payload, config);
 }
 export {
   ACCESSIBILITY_BOTS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adwait12345/telemetry-core",
-  "version": "0.1.2",
+  "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",