@getintel/agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GetIntel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @getintel/agent
+
+Shows which AI bots — ChatGPT, Perplexity, Claude, Gemini — read your pages,
+in GetIntel → Analytics → AI crawlers. Bots never run JavaScript, so this
+runs on your server. It only reports requests from GetIntel's AI bot list
+(refreshed hourly from GetIntel — no upgrades needed when bots change), sends
+after the response, and never throws.
+
+```sh
+npm install @getintel/agent
+```
+
+Your site key is in GetIntel → Analytics → AI crawlers → Install our server script.
+
+## Next.js
+
+On Next.js 16 the file is `proxy.ts` and the export is `proxy`; on 13–15 it's `middleware.ts` and `middleware`.
+
+```ts
+// middleware.ts
+import { getintel } from '@getintel/agent/next'
+
+export const middleware = getintel({ siteKey: 'gi_live_…' })
+```
+
+Already have a middleware? Use `createTracker`:
+
+```ts
+import { createTracker } from '@getintel/agent/next'
+const track = createTracker({ siteKey: 'gi_live_…' })
+
+export function middleware(request, event) {
+  track(request, event)
+  // …your code
+}
+```
+
+## Express
+
+```js
+const { getintel } = require('@getintel/agent/express')
+app.use(getintel({ siteKey: 'gi_live_…' }))
+```
+
+## Anything else
+
+```js
+const { createAgent } = require('@getintel/agent')
+const agent = createAgent({ siteKey: 'gi_live_…' })
+agent.track({ ua, ip, path, status }) // returns a promise that always resolves
+```
+
+Visitors from AI assistants are measured by the separate one-line visitor tag
+(AI visitors page), not this package.

package/express.d.ts

@@ -0,0 +1,6 @@
+import type { AgentOptions } from './index'
+
+type Next = (err?: unknown) => void
+
+/** Express / Connect middleware that reports AI bot visits after the response is sent. */
+export declare function getintel(options: AgentOptions): (req: any, res: any, next: Next) => void

package/express.js

@@ -0,0 +1,22 @@
+// @getintel/agent/express — Express / Connect middleware.
+//
+//   const { getintel } = require('@getintel/agent/express')
+//   app.use(getintel({ siteKey: 'gi_live_…' }))
+//
+// Reports after the response is sent (with its status code), so it never
+// slows a request down.
+
+const { createAgent, clientIp } = require('./index')
+
+function getintel(options) {
+  const agent = createAgent(options)
+  return function getintelMiddleware(req, res, next) {
+    const get = (k) => (typeof req.get === 'function' ? req.get(k) : req.headers[k])
+    res.on('finish', () => {
+      agent.track({ ua: get('user-agent'), ip: clientIp(get) || req.ip || '', path: (req.originalUrl || req.url || '/').split('?')[0], status: res.statusCode })
+    })
+    next()
+  }
+}
+
+module.exports = { getintel }

package/index.d.ts

@@ -0,0 +1,24 @@
+export interface AgentOptions {
+  /** Your site key from GetIntel → Analytics → AI crawlers (gi_live_…). */
+  siteKey: string
+  /** Where events are sent. Defaults to https://ingest.getintel.ai. */
+  endpoint?: string
+}
+
+export interface TrackInput {
+  ua?: string | null
+  ip?: string | null
+  path?: string | null
+  status?: number | null
+}
+
+export interface Agent {
+  /** Reports the request if it came from an AI bot. The promise always resolves. */
+  track(input?: TrackInput): Promise<void>
+  /** The matching bot user-agent token, or undefined. */
+  botFor(ua?: string | null): string | undefined
+}
+
+export declare const DEFAULT_ENDPOINT: string
+export declare function createAgent(options: AgentOptions): Agent
+export declare function clientIp(getHeader: (name: string) => string | null | undefined): string

package/index.js

@@ -0,0 +1,65 @@
+// @getintel/agent — core. Reports requests from AI bots to GetIntel
+// (Analytics → AI crawlers). Bots never run JavaScript, so this runs on your
+// server. Only requests whose user agent matches GetIntel's bot list are
+// sent (the list is downloaded from /v1/config and refreshed hourly), plus
+// one "ping" when the process starts so GetIntel can show it's installed.
+// Fire-and-forget: never throws, never delays your response.
+
+const DEFAULT_ENDPOINT = 'https://ingest.getintel.ai'
+const FALLBACK_BOTS = [
+  'OAI-SearchBot', 'ChatGPT-User', 'GPTBot', 'PerplexityBot', 'Perplexity-User',
+  'Claude-SearchBot', 'Claude-User', 'ClaudeBot', 'Google-Agent', 'Google-GeminiNotebook', 'Google-NotebookLM',
+]
+const HOUR = 60 * 60 * 1000
+const TIMEOUT_MS = 3000
+
+// Abort a request that hangs, where the runtime supports it (Node 18+, Edge).
+const withTimeout = () => (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function' ? { signal: AbortSignal.timeout(TIMEOUT_MS) } : {})
+
+function createAgent({ siteKey, endpoint = DEFAULT_ENDPOINT } = {}) {
+  if (!siteKey) throw new Error('@getintel/agent: siteKey is required')
+  const base = String(endpoint).replace(/\/+$/, '')
+  let bots = FALLBACK_BOTS
+  let fetchedAt = 0
+  let pinged = false
+
+  function refresh() {
+    if (Date.now() - fetchedAt < HOUR) return
+    fetchedAt = Date.now()
+    fetch(`${base}/v1/config`, withTimeout())
+      .then((r) => (r.ok ? r.json() : null))
+      .then((c) => { if (c && Array.isArray(c.bots)) bots = c.bots.map((b) => b.match).filter(Boolean) })
+      .catch(() => {})
+  }
+
+  function botFor(ua) {
+    const s = String(ua || '')
+    return bots.find((m) => s.includes(m))
+  }
+
+  // Returns a promise that always resolves — pass it to waitUntil where the
+  // runtime has one (Next.js middleware, Workers), ignore it elsewhere.
+  function track({ ua, ip, path, status } = {}) {
+    try {
+      refresh()
+      const events = []
+      if (!pinged) { pinged = true; events.push({ k: siteKey, t: 'ping' }) }
+      if (botFor(ua)) events.push({ k: siteKey, t: 'bot', ua: String(ua).slice(0, 400), ip, path, status })
+      if (!events.length) return Promise.resolve()
+      return fetch(`${base}/v1/hit`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(events), ...withTimeout() })
+        .then(() => {}, () => {})
+    } catch {
+      return Promise.resolve()
+    }
+  }
+
+  return { track, botFor }
+}
+
+// The real client IP behind common proxies / CDNs.
+function clientIp(getHeader) {
+  const xff = getHeader('x-forwarded-for')
+  return getHeader('cf-connecting-ip') || (xff && xff.split(',')[0].trim()) || getHeader('x-real-ip') || ''
+}
+
+module.exports = { createAgent, clientIp, DEFAULT_ENDPOINT }

package/next.d.ts

@@ -0,0 +1,8 @@
+import type { NextRequest, NextFetchEvent, NextResponse } from 'next/server'
+import type { AgentOptions } from './index'
+
+/** Middleware (Next.js 13–15 middleware.ts, or Next.js 16 proxy.ts) that reports AI bot visits. */
+export declare function getintel(options: AgentOptions): (request: NextRequest, event?: NextFetchEvent) => NextResponse
+
+/** For an existing middleware or proxy: call track(request, event) inside it. */
+export declare function createTracker(options: AgentOptions): (request: NextRequest, event?: NextFetchEvent) => Promise<void>

package/next.js

@@ -0,0 +1,33 @@
+// @getintel/agent/next — Next.js middleware (works on the Edge runtime).
+//
+//   // middleware.ts
+//   import { getintel } from '@getintel/agent/next'
+//   export const middleware = getintel({ siteKey: 'gi_live_…' })
+//
+// Already have a middleware? Call track() inside it instead:
+//   import { createTracker } from '@getintel/agent/next'
+//   const track = createTracker({ siteKey: 'gi_live_…' })
+//   export function middleware(request, event) { track(request, event); /* …your code… */ }
+
+const { NextResponse } = require('next/server')
+const { createAgent, clientIp } = require('./index')
+
+function createTracker(options) {
+  const agent = createAgent(options)
+  return function track(request, event) {
+    const h = request.headers
+    const p = agent.track({ ua: h.get('user-agent'), ip: clientIp((k) => h.get(k)), path: request.nextUrl.pathname })
+    if (event && typeof event.waitUntil === 'function') event.waitUntil(p)
+    return p
+  }
+}
+
+function getintel(options) {
+  const track = createTracker(options)
+  return function middleware(request, event) {
+    track(request, event)
+    return NextResponse.next()
+  }
+}
+
+module.exports = { getintel, createTracker }

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@getintel/agent",
+  "version": "0.1.0",
+  "description": "Report AI bot visits (ChatGPT, Perplexity, Claude, Gemini) from your server to GetIntel — Analytics → AI crawlers.",
+  "license": "MIT",
+  "homepage": "https://getintel.ai/docs/integrations/getintel-script/",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./next": {
+      "types": "./next.d.ts",
+      "default": "./next.js"
+    },
+    "./express": {
+      "types": "./express.d.ts",
+      "default": "./express.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "next.js",
+    "next.d.ts",
+    "express.js",
+    "express.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "next": ">=13"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "crawlers",
+    "chatgpt",
+    "perplexity",
+    "claude",
+    "analytics",
+    "getintel"
+  ],
+  "types": "index.d.ts",
+  "author": "GetIntel (https://getintel.ai)"
+}