@aranx/ai-analytics 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aranx
+
+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

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @aranx/ai-analytics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Records AI traffic on your site and sends it to [Aranx](https://aranx.com):
+
+- **Bot visits.** Requests from AI search bots (`OAI-SearchBot`,
+  `Claude-SearchBot`, `PerplexityBot`) and from AI apps that open a page while
+  they answer a question (`ChatGPT-User`, `Claude-User`, `Perplexity-User`).
+  Training crawlers such as `GPTBot` are not recorded.
+- **Visitors from AI apps.** People who open your site from a link in
+  ChatGPT, Perplexity, Gemini, Claude, or Copilot.
+
+AI bots do not run JavaScript, so only server code can see their visits. The
+package runs in your server's request path and sends nothing for ordinary
+traffic.
+
+## Install
+
+```sh
+npm install @aranx/ai-analytics
+```
+
+Copy the traffic key from **AI visibility** in Aranx and set it as the
+`ARANX_TRAFFIC_KEY` environment variable (or Worker secret). Keep it on the
+server. Without a key, the package does nothing.
+
+## Next.js
+
+```ts
+// proxy.ts (middleware.ts before Next.js 16)
+import { withAiTraffic } from '@aranx/ai-analytics/next';
+
+export const proxy = withAiTraffic();
+
+// Skip static files.
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)']
+};
+```
+
+To keep an existing proxy, wrap it: `withAiTraffic(myProxy)`.
+
+## Cloudflare Workers and Shopify Hydrogen (Oxygen)
+
+```ts
+import { withAiTraffic } from '@aranx/ai-analytics/fetch';
+
+export default {
+  fetch: withAiTraffic(async (request, env, ctx) => handle(request, env, ctx))
+};
+```
+
+The key comes from the `ARANX_TRAFFIC_KEY` binding. In Hydrogen, wrap the
+`fetch` handler in `server.ts`.
+
+## Hono
+
+```ts
+import { aiTraffic } from '@aranx/ai-analytics/hono';
+
+app.use(aiTraffic());
+```
+
+## Express
+
+```ts
+import { aiTraffic } from '@aranx/ai-analytics/express';
+
+app.use(aiTraffic());
+```
+
+Express keeps one process between requests, so events go out in batches
+every 10 seconds. Set `app.set('trust proxy', true)` behind a load balancer
+so the client IP is right.
+
+## Other frameworks
+
+Any framework with a standard `Request` (React Router, Remix, SvelteKit,
+Astro, Deno, Bun) can call the tracker after it builds the response:
+
+```ts
+import { createAiTraffic } from '@aranx/ai-analytics';
+import { trackRequest } from '@aranx/ai-analytics/fetch';
+
+const tracker = createAiTraffic();
+
+// SvelteKit hooks.server.ts
+export async function handle({ event, resolve }) {
+  const response = await resolve(event);
+  void trackRequest(tracker, event.request, response);
+  return response;
+}
+```
+
+Fastify and Koa can pass the Node request to `nodeRequestInfo` from
+`@aranx/ai-analytics/express` and then call `tracker.track(info)`.
+
+## Other languages
+
+Any server can post events to the endpoint directly:
+
+```http
+POST https://aranx.com/api/v1/ai-traffic/events
+Authorization: Bearer arx_tk_...
+Content-Type: application/json
+
+{
+  "events": [
+    {
+      "type": "bot_visit",
+      "url": "https://example.com/pricing",
+      "user_agent": "Mozilla/5.0 (compatible; ChatGPT-User/1.0)",
+      "status": 200,
+      "occurred_at": "2026-11-03T10:00:00Z"
+    },
+    {
+      "type": "ai_referral",
+      "url": "https://example.com/blog/post?utm_source=chatgpt.com",
+      "referrer": "https://chatgpt.com/",
+      "occurred_at": "2026-11-03T10:00:05Z"
+    }
+  ]
+}
+```
+
+- `status` and `occurred_at` are optional. Aranx uses the time it receives an
+  event when `occurred_at` is missing, and ignores events older than 3 days.
+- Each request takes 1 to 500 events and at most 512 KiB. `url` and
+  `referrer` take at most 2,048 characters.
+- Aranx classifies each event again and ignores events it cannot place, such
+  as an unknown user agent or a host the website does not own.
+- The response is `202` with `{ "accepted": n, "ignored": n }`. Other
+  responses are `400` (bad body), `401` (bad key), `403` (subscription
+  inactive), `413` (body too large), and `429` (over 1,200 requests per minute,
+  retry after 60 seconds).
+
+## Options
+
+```ts
+createAiTraffic({
+  key: 'arx_tk_...', // default: ARANX_TRAFFIC_KEY
+  endpoint: 'https://aranx.com/api/v1/ai-traffic/events', // or ARANX_TRAFFIC_ENDPOINT
+  batch: { maxEvents: 100, intervalMs: 10_000 }, // default: off, on for Express
+  timeoutMs: 5_000,
+  onError: (error) => {} // default: one console warning per minute
+});
+```
+
+## What is sent
+
+For each AI request: the page URL without its query (only `utm_source` is
+kept), the user agent, the response status when known, and the time. Bot
+visits also carry the client IP. Aranx does not use or store it yet. It is
+reserved for checking the IP ranges that the AI companies publish. Visitor requests carry the referrer, and no IP or
+cookie.
+
+Tracking never throws and never delays your response. A failed send is
+dropped.

package/dist/adapters/express.d.ts

@@ -0,0 +1,37 @@
+import type { AiTrafficOptions } from '../client.js';
+import type { AiTrafficRequestInfo } from '../events.js';
+type HeaderValue = string | string[] | undefined;
+/** The parts of a Node `IncomingMessage` (or Express request) it reads. */
+export interface NodeLikeRequest {
+    method?: string;
+    url?: string;
+    /** Express keeps the full path here when a router strips a prefix. */
+    originalUrl?: string;
+    /** Express sets it from `X-Forwarded-Proto` when `trust proxy` is on. */
+    protocol?: string;
+    headers: Record<string, HeaderValue>;
+    socket?: {
+        remoteAddress?: string;
+        encrypted?: boolean;
+    };
+}
+export interface NodeLikeResponse {
+    statusCode: number;
+    once(event: 'finish', listener: () => void): unknown;
+}
+/**
+ * Reads the fields the tracker needs from a Node request. Use it in Fastify
+ * (`request.raw`) and Koa (`ctx.req`).
+ */
+export declare function nodeRequestInfo(req: NodeLikeRequest, status?: number): AiTrafficRequestInfo;
+/**
+ * Express or Connect middleware. It records each request after the response
+ * finishes and sends events in batches, because the server process lives
+ * between requests.
+ *
+ * ```ts
+ * app.use(aiTraffic());
+ * ```
+ */
+export declare function aiTraffic(options?: AiTrafficOptions): (req: NodeLikeRequest, res: NodeLikeResponse, next: () => void) => void;
+export {};

package/dist/adapters/express.js

@@ -0,0 +1,53 @@
+import { trackerFor } from './shared.js';
+function header(req, name) {
+    const value = req.headers[name];
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+}
+/**
+ * Reads the fields the tracker needs from a Node request. Use it in Fastify
+ * (`request.raw`) and Koa (`ctx.req`).
+ */
+export function nodeRequestInfo(req, status) {
+    const forwardedProto = header(req, 'x-forwarded-proto')?.split(',')[0];
+    const protocol = req.protocol ??
+        forwardedProto?.trim() ??
+        (req.socket?.encrypted ? 'https' : 'http');
+    const host = header(req, 'x-forwarded-host')?.split(',')[0]?.trim() ??
+        header(req, 'host') ??
+        'localhost';
+    const forwardedFor = header(req, 'x-forwarded-for')?.split(',')[0]?.trim();
+    return {
+        url: `${protocol}://${host}${req.originalUrl ?? req.url ?? '/'}`,
+        method: req.method,
+        userAgent: header(req, 'user-agent'),
+        referrer: header(req, 'referer'),
+        ip: header(req, 'cf-connecting-ip') ??
+            forwardedFor ??
+            req.socket?.remoteAddress ??
+            null,
+        fetchDest: header(req, 'sec-fetch-dest'),
+        status
+    };
+}
+/**
+ * Express or Connect middleware. It records each request after the response
+ * finishes and sends events in batches, because the server process lives
+ * between requests.
+ *
+ * ```ts
+ * app.use(aiTraffic());
+ * ```
+ */
+export function aiTraffic(options = {}) {
+    const tracker = trackerFor({ batch: true, ...options });
+    return (req, res, next) => {
+        if (tracker.enabled) {
+            res.once('finish', () => {
+                void tracker.track(nodeRequestInfo(req, res.statusCode));
+            });
+        }
+        next();
+    };
+}

package/dist/adapters/fetch.d.ts

@@ -0,0 +1,19 @@
+import type { AiTrafficTracker } from '../client.js';
+import { type AiTrafficOptionsInput, type WaitUntilContext } from './shared.js';
+export { fetchRequestInfo, type WaitUntilContext } from './shared.js';
+/**
+ * Records a Fetch API request. Use it in any framework that exposes the
+ * standard `Request`: React Router, Remix, SvelteKit, Astro, Hydrogen, Deno,
+ * and Bun.
+ */
+export declare function trackRequest(tracker: AiTrafficTracker, request: Request, response?: Response): Promise<void>;
+type FetchHandler<Env, Ctx> = (request: Request, env: Env, ctx: Ctx) => Response | Promise<Response>;
+/**
+ * Wraps a Cloudflare Worker or Shopify Oxygen `fetch` handler. The key comes
+ * from the `ARANX_TRAFFIC_KEY` binding unless `options` sets it.
+ *
+ * ```ts
+ * export default { fetch: withAiTraffic(handler) };
+ * ```
+ */
+export declare function withAiTraffic<Env, Ctx extends WaitUntilContext>(handler: FetchHandler<Env, Ctx>, options?: AiTrafficOptionsInput<Env>): FetchHandler<Env, Ctx>;

package/dist/adapters/fetch.js

@@ -0,0 +1,28 @@
+import { fetchRequestInfo, resolveOptions, trackerFor } from './shared.js';
+export { fetchRequestInfo } from './shared.js';
+/**
+ * Records a Fetch API request. Use it in any framework that exposes the
+ * standard `Request`: React Router, Remix, SvelteKit, Astro, Hydrogen, Deno,
+ * and Bun.
+ */
+export function trackRequest(tracker, request, response) {
+    return tracker.track(fetchRequestInfo(request, response?.status));
+}
+/**
+ * Wraps a Cloudflare Worker or Shopify Oxygen `fetch` handler. The key comes
+ * from the `ARANX_TRAFFIC_KEY` binding unless `options` sets it.
+ *
+ * ```ts
+ * export default { fetch: withAiTraffic(handler) };
+ * ```
+ */
+export function withAiTraffic(handler, options) {
+    return async (request, env, ctx) => {
+        const response = await handler(request, env, ctx);
+        const tracker = trackerFor(resolveOptions(options, env));
+        if (tracker.enabled) {
+            ctx.waitUntil(trackRequest(tracker, request, response));
+        }
+        return response;
+    };
+}

package/dist/adapters/hono.d.ts

@@ -0,0 +1,20 @@
+import { type AiTrafficOptionsInput, type WaitUntilContext } from './shared.js';
+/** The parts of a Hono context the middleware reads. */
+export interface HonoLikeContext<Env = unknown> {
+    req: {
+        raw: Request;
+    };
+    res: Response;
+    env: Env;
+    /** Hono throws when the runtime has no execution context, as on Node. */
+    readonly executionCtx: WaitUntilContext;
+}
+/**
+ * Hono middleware. On Workers the key comes from the `ARANX_TRAFFIC_KEY`
+ * binding, on Node from `process.env`.
+ *
+ * ```ts
+ * app.use(aiTraffic());
+ * ```
+ */
+export declare function aiTraffic<Env = unknown>(options?: AiTrafficOptionsInput<Env>): (c: HonoLikeContext<Env>, next: () => Promise<void>) => Promise<void>;

package/dist/adapters/hono.js

@@ -0,0 +1,29 @@
+import { fetchRequestInfo, resolveOptions, trackerFor } from './shared.js';
+/**
+ * Hono middleware. On Workers the key comes from the `ARANX_TRAFFIC_KEY`
+ * binding, on Node from `process.env`.
+ *
+ * ```ts
+ * app.use(aiTraffic());
+ * ```
+ */
+export function aiTraffic(options) {
+    return async (c, next) => {
+        await next();
+        const tracker = trackerFor(resolveOptions(options, c.env));
+        if (!tracker.enabled)
+            return;
+        const pending = tracker.track(fetchRequestInfo(c.req.raw, c.res.status));
+        let ctx;
+        try {
+            ctx = c.executionCtx;
+        }
+        catch {
+            ctx = undefined;
+        }
+        if (ctx)
+            ctx.waitUntil(pending);
+        else
+            void pending;
+    };
+}

package/dist/adapters/next.d.ts

@@ -0,0 +1,16 @@
+import type { AiTrafficOptions } from '../client.js';
+import { type WaitUntilContext } from './shared.js';
+type Proxy<Req extends Request, Ev extends WaitUntilContext, Result> = (request: Req, event: Ev) => Result | Promise<Result>;
+/**
+ * Wraps a Next.js `proxy` (named `middleware` before Next.js 16). With no
+ * proxy, the request continues unchanged. The proxy runs before the page, so
+ * events carry no response status.
+ *
+ * ```ts
+ * // proxy.ts
+ * import { withAiTraffic } from '@aranx/ai-analytics/next';
+ * export const proxy = withAiTraffic();
+ * ```
+ */
+export declare function withAiTraffic<Req extends Request, Ev extends WaitUntilContext, Result = undefined>(proxy?: Proxy<Req, Ev, Result>, options?: AiTrafficOptions): (request: Req, event: Ev) => Promise<Result | undefined>;
+export {};

package/dist/adapters/next.js

@@ -0,0 +1,21 @@
+import { fetchRequestInfo, trackerFor } from './shared.js';
+/**
+ * Wraps a Next.js `proxy` (named `middleware` before Next.js 16). With no
+ * proxy, the request continues unchanged. The proxy runs before the page, so
+ * events carry no response status.
+ *
+ * ```ts
+ * // proxy.ts
+ * import { withAiTraffic } from '@aranx/ai-analytics/next';
+ * export const proxy = withAiTraffic();
+ * ```
+ */
+export function withAiTraffic(proxy, options = {}) {
+    return async (request, event) => {
+        const tracker = trackerFor(options);
+        if (tracker.enabled) {
+            event.waitUntil(tracker.track(fetchRequestInfo(request)));
+        }
+        return proxy ? proxy(request, event) : undefined;
+    };
+}

package/dist/adapters/shared.d.ts

@@ -0,0 +1,22 @@
+import { type AiTrafficOptions, type AiTrafficTracker } from '../client.js';
+import { type AiTrafficRequestInfo } from '../events.js';
+/** The `waitUntil` that Workers, Vercel, Netlify, and Next.js provide. */
+export interface WaitUntilContext {
+    waitUntil(promise: Promise<unknown>): void;
+}
+/** Options, or a function that builds them from the platform bindings. */
+export type AiTrafficOptionsInput<Env> = AiTrafficOptions | ((env: Env) => AiTrafficOptions);
+/**
+ * Returns one tracker per configuration. Workers pass bindings on every
+ * request, so a new tracker per request would drop batching and warn on
+ * every call.
+ */
+export declare function trackerFor(options: AiTrafficOptions): AiTrafficTracker;
+/**
+ * Resolves options for platforms that pass bindings (Workers, Oxygen). With
+ * no options, the key and endpoint come from the `ARANX_TRAFFIC_KEY` and
+ * `ARANX_TRAFFIC_ENDPOINT` bindings, then from `process.env`.
+ */
+export declare function resolveOptions<Env>(input: AiTrafficOptionsInput<Env> | undefined, env: Env): AiTrafficOptions;
+/** Reads the fields the tracker needs from a Fetch API request. */
+export declare function fetchRequestInfo(request: Request, status?: number): AiTrafficRequestInfo;

package/dist/adapters/shared.js

@@ -0,0 +1,77 @@
+import { createAiTraffic, readEnv } from '../client.js';
+import { clientIpFromHeaders } from '../events.js';
+/** Stands in for an absent `fetch` or `onError` in the cache below. */
+const NONE = {};
+/**
+ * Trackers by `fetch`, then `onError` (by function identity), then the
+ * remaining options. Two callers with the same key but different handlers
+ * get different trackers.
+ */
+const trackers = new WeakMap();
+function cacheFor(options) {
+    const fetchKey = options.fetch ?? NONE;
+    const onErrorKey = options.onError ?? NONE;
+    let byOnError = trackers.get(fetchKey);
+    if (!byOnError) {
+        byOnError = new WeakMap();
+        trackers.set(fetchKey, byOnError);
+    }
+    let cache = byOnError.get(onErrorKey);
+    if (!cache) {
+        cache = new Map();
+        byOnError.set(onErrorKey, cache);
+    }
+    return cache;
+}
+/**
+ * Returns one tracker per configuration. Workers pass bindings on every
+ * request, so a new tracker per request would drop batching and warn on
+ * every call.
+ */
+export function trackerFor(options) {
+    const id = JSON.stringify([
+        options.key ?? readEnv('ARANX_TRAFFIC_KEY') ?? null,
+        options.endpoint ?? readEnv('ARANX_TRAFFIC_ENDPOINT') ?? null,
+        options.batch ?? null,
+        options.timeoutMs ?? null
+    ]);
+    const cache = cacheFor(options);
+    let tracker = cache.get(id);
+    if (!tracker) {
+        tracker = createAiTraffic(options);
+        cache.set(id, tracker);
+    }
+    return tracker;
+}
+function stringBinding(env, name) {
+    if (!env || typeof env !== 'object')
+        return undefined;
+    const value = env[name];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Resolves options for platforms that pass bindings (Workers, Oxygen). With
+ * no options, the key and endpoint come from the `ARANX_TRAFFIC_KEY` and
+ * `ARANX_TRAFFIC_ENDPOINT` bindings, then from `process.env`.
+ */
+export function resolveOptions(input, env) {
+    if (typeof input === 'function')
+        return input(env);
+    return {
+        key: stringBinding(env, 'ARANX_TRAFFIC_KEY'),
+        endpoint: stringBinding(env, 'ARANX_TRAFFIC_ENDPOINT'),
+        ...input
+    };
+}
+/** Reads the fields the tracker needs from a Fetch API request. */
+export function fetchRequestInfo(request, status) {
+    return {
+        url: request.url,
+        method: request.method,
+        userAgent: request.headers.get('user-agent'),
+        referrer: request.headers.get('referer'),
+        ip: clientIpFromHeaders(request.headers),
+        fetchDest: request.headers.get('sec-fetch-dest'),
+        status
+    };
+}

package/dist/catalog.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The AI agents and AI apps that Aranx tracks. This file is the single list:
+ * the npm package and the Aranx server read it, and the WordPress plugin
+ * build will read it.
+ *
+ * Training crawlers (GPTBot, ClaudeBot, CCBot) are left out on purpose. They
+ * collect pages for future models and say nothing about answers today.
+ */
+export type AiOperator = 'openai' | 'anthropic' | 'perplexity';
+/**
+ * `search` bots build the index an AI app searches. `user` fetchers open a
+ * page while the app answers a person's question.
+ */
+export type AiAgentPurpose = 'search' | 'user';
+export interface AiAgent {
+    /** The user-agent token, also the name stored and shown. */
+    name: string;
+    operator: AiOperator;
+    purpose: AiAgentPurpose;
+}
+export declare const AI_AGENTS: readonly AiAgent[];
+export type AiAppId = 'chatgpt' | 'perplexity' | 'gemini' | 'claude' | 'copilot';
+export interface AiApp {
+    id: AiAppId;
+    /** Referrer hosts. A subdomain of a listed host also matches. */
+    hosts: readonly string[];
+    /** `utm_source` values the app adds to its outbound links. */
+    utmSources: readonly string[];
+}
+export declare const AI_APPS: readonly AiApp[];

package/dist/catalog.js

@@ -0,0 +1,35 @@
+/**
+ * The AI agents and AI apps that Aranx tracks. This file is the single list:
+ * the npm package and the Aranx server read it, and the WordPress plugin
+ * build will read it.
+ *
+ * Training crawlers (GPTBot, ClaudeBot, CCBot) are left out on purpose. They
+ * collect pages for future models and say nothing about answers today.
+ */
+export const AI_AGENTS = [
+    { name: 'OAI-SearchBot', operator: 'openai', purpose: 'search' },
+    { name: 'ChatGPT-User', operator: 'openai', purpose: 'user' },
+    { name: 'Claude-SearchBot', operator: 'anthropic', purpose: 'search' },
+    { name: 'Claude-User', operator: 'anthropic', purpose: 'user' },
+    { name: 'PerplexityBot', operator: 'perplexity', purpose: 'search' },
+    { name: 'Perplexity-User', operator: 'perplexity', purpose: 'user' }
+];
+export const AI_APPS = [
+    {
+        id: 'chatgpt',
+        hosts: ['chatgpt.com', 'chat.openai.com'],
+        utmSources: ['chatgpt.com']
+    },
+    { id: 'perplexity', hosts: ['perplexity.ai'], utmSources: [] },
+    {
+        id: 'gemini',
+        hosts: ['gemini.google.com', 'bard.google.com'],
+        utmSources: []
+    },
+    { id: 'claude', hosts: ['claude.ai'], utmSources: [] },
+    {
+        id: 'copilot',
+        hosts: ['copilot.microsoft.com', 'copilot.cloud.microsoft'],
+        utmSources: []
+    }
+];

package/dist/classify.d.ts

@@ -0,0 +1,16 @@
+import { type AiAgent, type AiApp } from './catalog.js';
+/** Returns the tracked AI agent named in a user-agent string. */
+export declare function matchAiAgent(userAgent: string | null | undefined): AiAgent | null;
+/**
+ * Returns the AI app a visitor came from. The app is known from the
+ * `utm_source` of the landing URL or from the referrer host.
+ */
+export declare function matchAiApp(input: {
+    url: string;
+    referrer?: string | null;
+}): AiApp | null;
+/**
+ * Keeps the origin, the path, and `utm_source`. Other query parameters can
+ * hold personal data, such as an email address in a sign-in link.
+ */
+export declare function sanitizeUrl(value: string): string | null;

package/dist/classify.js

@@ -0,0 +1,65 @@
+import { AI_AGENTS, AI_APPS } from './catalog.js';
+const AGENT_PATTERNS = AI_AGENTS.map((agent) => ({
+    agent,
+    // A token match, so `Claude-User` never matches inside a longer name.
+    pattern: new RegExp(`(?:^|[^a-z0-9-])${agent.name.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')}(?:[^a-z0-9-]|$)`, 'i')
+}));
+/** Returns the tracked AI agent named in a user-agent string. */
+export function matchAiAgent(userAgent) {
+    if (!userAgent)
+        return null;
+    for (const { agent, pattern } of AGENT_PATTERNS) {
+        if (pattern.test(userAgent))
+            return agent;
+    }
+    return null;
+}
+function parseUrl(value) {
+    if (!value)
+        return null;
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+function hostMatches(host, hosts) {
+    return hosts.some((h) => host === h || host.endsWith(`.${h}`));
+}
+/**
+ * Returns the AI app a visitor came from. The app is known from the
+ * `utm_source` of the landing URL or from the referrer host.
+ */
+export function matchAiApp(input) {
+    const utmSource = parseUrl(input.url)
+        ?.searchParams.get('utm_source')
+        ?.toLowerCase();
+    if (utmSource) {
+        const app = AI_APPS.find((a) => a.utmSources.includes(utmSource));
+        if (app)
+            return app;
+    }
+    const referrerHost = parseUrl(input.referrer)?.hostname.toLowerCase();
+    if (referrerHost) {
+        const app = AI_APPS.find((a) => hostMatches(referrerHost, a.hosts));
+        if (app)
+            return app;
+    }
+    return null;
+}
+/**
+ * Keeps the origin, the path, and `utm_source`. Other query parameters can
+ * hold personal data, such as an email address in a sign-in link.
+ */
+export function sanitizeUrl(value) {
+    const url = parseUrl(value);
+    if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
+        return null;
+    }
+    const utmSource = url.searchParams.get('utm_source');
+    const query = utmSource
+        ? `?${new URLSearchParams({ utm_source: utmSource }).toString()}`
+        : '';
+    return `${url.origin}${url.pathname}${query}`;
+}

package/dist/client.d.ts

@@ -0,0 +1,47 @@
+import { type AiTrafficEvent, type AiTrafficRequestInfo } from './events.js';
+export declare const DEFAULT_ENDPOINT = "https://aranx.com/api/v1/ai-traffic/events";
+/** The most events the endpoint accepts in one request. */
+export declare const MAX_EVENTS_PER_REQUEST = 500;
+/** The largest request body the endpoint accepts, in UTF-8 bytes. */
+export declare const MAX_REQUEST_BYTES: number;
+/**
+ * Serializes events into request bodies of at most MAX_EVENTS_PER_REQUEST
+ * events and TARGET_REQUEST_BYTES bytes each.
+ */
+export declare function toRequestBodies(events: AiTrafficEvent[]): string[];
+export interface AiTrafficBatchOptions {
+    /** Send when this many events are queued. Default 100. */
+    maxEvents?: number;
+    /** Send queued events after this delay. Default 10 seconds. */
+    intervalMs?: number;
+}
+export interface AiTrafficOptions {
+    /** The website's traffic key. Default: `ARANX_TRAFFIC_KEY`. */
+    key?: string;
+    /** Default: `ARANX_TRAFFIC_ENDPOINT`, then the Aranx production URL. */
+    endpoint?: string;
+    /**
+     * Queue events and send them together. Use it on long-running servers.
+     * Serverless functions and Workers keep no memory between requests, so
+     * they send each event at once (the default).
+     */
+    batch?: boolean | AiTrafficBatchOptions;
+    /** Abort a send after this delay. Default 5 seconds. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    /** Called when a send fails. Default: a console warning. */
+    onError?: (error: unknown) => void;
+}
+export interface AiTrafficTracker {
+    /** False when no valid key is set. Tracking then does nothing. */
+    readonly enabled: boolean;
+    /**
+     * Records the request when it is AI traffic. The promise never rejects.
+     * Pass it to `waitUntil` where the platform has one.
+     */
+    track(info: AiTrafficRequestInfo): Promise<void>;
+    /** Sends queued events now. */
+    flush(): Promise<void>;
+}
+export declare function readEnv(name: string): string | undefined;
+export declare function createAiTraffic(options?: AiTrafficOptions): AiTrafficTracker;

package/dist/client.js

@@ -0,0 +1,156 @@
+import { toAiTrafficEvent } from './events.js';
+export const DEFAULT_ENDPOINT = 'https://aranx.com/api/v1/ai-traffic/events';
+/** The most events the endpoint accepts in one request. */
+export const MAX_EVENTS_PER_REQUEST = 500;
+/** The largest request body the endpoint accepts, in UTF-8 bytes. */
+export const MAX_REQUEST_BYTES = 512 * 1024;
+/** The client keeps each request below this size, under the server cap. */
+const TARGET_REQUEST_BYTES = 448 * 1024;
+const ENVELOPE = { open: '{"events":[', close: ']}' };
+const encoder = new TextEncoder();
+/**
+ * Serializes events into request bodies of at most MAX_EVENTS_PER_REQUEST
+ * events and TARGET_REQUEST_BYTES bytes each.
+ */
+export function toRequestBodies(events) {
+    const envelopeBytes = encoder.encode(ENVELOPE.open + ENVELOPE.close).length;
+    const bodies = [];
+    let items = [];
+    let bytes = envelopeBytes;
+    const close = () => {
+        bodies.push(ENVELOPE.open + items.join(',') + ENVELOPE.close);
+        items = [];
+        bytes = envelopeBytes;
+    };
+    for (const event of events) {
+        const item = JSON.stringify(event);
+        const itemBytes = encoder.encode(item).length;
+        if (items.length >= MAX_EVENTS_PER_REQUEST ||
+            (items.length > 0 && bytes + 1 + itemBytes > TARGET_REQUEST_BYTES)) {
+            close();
+        }
+        // A comma separates every item after the first.
+        bytes += itemBytes + (items.length > 0 ? 1 : 0);
+        items.push(item);
+    }
+    if (items.length > 0)
+        close();
+    return bodies;
+}
+const KEY_PATTERN = /^arx_tk_[A-Za-z0-9]{32,64}$/;
+export function readEnv(name) {
+    const env = globalThis.process?.env;
+    const value = env?.[name];
+    return value && value.trim() ? value.trim() : undefined;
+}
+function defaultOnError() {
+    let lastWarnedAt = 0;
+    return (error) => {
+        const now = Date.now();
+        if (now - lastWarnedAt < 60_000)
+            return;
+        lastWarnedAt = now;
+        console.warn('[@aranx/ai-analytics] Could not send AI traffic:', error);
+    };
+}
+function resolveBatch(batch) {
+    if (!batch)
+        return null;
+    const options = batch === true ? {} : batch;
+    return {
+        maxEvents: Math.min(Math.max(1, options.maxEvents ?? 100), MAX_EVENTS_PER_REQUEST),
+        intervalMs: Math.max(1_000, options.intervalMs ?? 10_000)
+    };
+}
+const disabledTracker = {
+    enabled: false,
+    track: () => Promise.resolve(),
+    flush: () => Promise.resolve()
+};
+export function createAiTraffic(options = {}) {
+    const key = options.key ?? readEnv('ARANX_TRAFFIC_KEY');
+    if (!key || !KEY_PATTERN.test(key)) {
+        console.warn(key
+            ? '[@aranx/ai-analytics] The traffic key is malformed. AI traffic is not tracked.'
+            : '[@aranx/ai-analytics] ARANX_TRAFFIC_KEY is not set. AI traffic is not tracked.');
+        return disabledTracker;
+    }
+    const endpoint = options.endpoint ??
+        readEnv('ARANX_TRAFFIC_ENDPOINT') ??
+        DEFAULT_ENDPOINT;
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const reportError = options.onError ?? defaultOnError();
+    // A throwing handler must not break the promise that tracking never
+    // rejects.
+    const onError = (error) => {
+        try {
+            reportError(error);
+        }
+        catch {
+            // Ignored on purpose.
+        }
+    };
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const batch = resolveBatch(options.batch);
+    let queue = [];
+    let timer = null;
+    async function post(body) {
+        try {
+            const response = await doFetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${key}`,
+                    'Content-Type': 'application/json'
+                },
+                body,
+                signal: AbortSignal.timeout(timeoutMs)
+            });
+            if (!response.ok) {
+                onError(new Error(`Aranx responded with HTTP ${response.status}`));
+            }
+        }
+        catch (error) {
+            onError(error);
+        }
+    }
+    async function send(events) {
+        for (const body of toRequestBodies(events))
+            await post(body);
+    }
+    function flush() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (queue.length === 0)
+            return Promise.resolve();
+        const events = queue;
+        queue = [];
+        return send(events);
+    }
+    function track(info) {
+        let event;
+        try {
+            event = toAiTrafficEvent(info);
+        }
+        catch (error) {
+            onError(error);
+            return Promise.resolve();
+        }
+        if (!event)
+            return Promise.resolve();
+        if (!batch)
+            return send([event]);
+        queue.push(event);
+        if (queue.length >= batch.maxEvents)
+            return flush();
+        if (!timer) {
+            timer = setTimeout(() => void flush(), batch.intervalMs);
+            // Node keeps a process alive for a pending timer. A queue of
+            // traffic counts must not.
+            timer.unref?.();
+        }
+        return Promise.resolve();
+    }
+    return { enabled: true, track, flush };
+}

package/dist/events.d.ts

@@ -0,0 +1,45 @@
+/** The longest `url` or `referrer` the endpoint accepts. */
+export declare const MAX_URL_LENGTH = 2048;
+/** A page request from a tracked AI agent. */
+export interface BotVisitEvent {
+    type: 'bot_visit';
+    url: string;
+    user_agent: string;
+    /** HTTP status of the response, when the caller knows it. */
+    status?: number;
+    /**
+     * Client IP. The endpoint accepts it but does not use it yet: Aranx
+     * neither checks nor stores it.
+     */
+    ip?: string;
+    occurred_at: string;
+}
+/** A person who opened the site from a link in an AI app. */
+export interface AiReferralEvent {
+    type: 'ai_referral';
+    url: string;
+    referrer?: string;
+    status?: number;
+    occurred_at: string;
+}
+export type AiTrafficEvent = BotVisitEvent | AiReferralEvent;
+/** The request fields an adapter reads from its framework. */
+export interface AiTrafficRequestInfo {
+    url: string;
+    method?: string | null;
+    userAgent?: string | null;
+    referrer?: string | null;
+    ip?: string | null;
+    status?: number | null;
+    /** The `Sec-Fetch-Dest` header. Browsers send `document` for pages. */
+    fetchDest?: string | null;
+}
+/**
+ * Turns a request into an event, or returns null when the request is not AI
+ * traffic. Only GET and HEAD requests count.
+ */
+export declare function toAiTrafficEvent(info: AiTrafficRequestInfo, now?: Date): AiTrafficEvent | null;
+/** Reads the client IP from the headers that hosts and CDNs set. */
+export declare function clientIpFromHeaders(headers: {
+    get(name: string): string | null;
+}): string | null;

package/dist/events.js

@@ -0,0 +1,59 @@
+import { matchAiAgent, matchAiApp, sanitizeUrl } from './classify.js';
+/** The longest `url` or `referrer` the endpoint accepts. */
+export const MAX_URL_LENGTH = 2048;
+/** The longest `ip` the endpoint accepts. A longer value is not sent. */
+const MAX_IP_LENGTH = 64;
+/**
+ * Turns a request into an event, or returns null when the request is not AI
+ * traffic. Only GET and HEAD requests count.
+ */
+export function toAiTrafficEvent(info, now = new Date()) {
+    const method = info.method?.toUpperCase();
+    if (method && method !== 'GET' && method !== 'HEAD')
+        return null;
+    const url = sanitizeUrl(info.url);
+    // The endpoint rejects longer URLs, so such an event is not sent.
+    if (!url || url.length > MAX_URL_LENGTH)
+        return null;
+    const status = typeof info.status === 'number' && info.status > 0
+        ? info.status
+        : undefined;
+    const occurred_at = now.toISOString();
+    if (info.userAgent && matchAiAgent(info.userAgent)) {
+        return {
+            type: 'bot_visit',
+            url,
+            user_agent: info.userAgent.slice(0, 512),
+            ...(status !== undefined && { status }),
+            ...(info.ip && info.ip.length <= MAX_IP_LENGTH && { ip: info.ip }),
+            occurred_at
+        };
+    }
+    // Images, scripts, and API calls of a page carry the page as referrer.
+    // Only the page itself is the landing.
+    if (info.fetchDest && info.fetchDest !== 'document')
+        return null;
+    if (matchAiApp({ url: info.url, referrer: info.referrer })) {
+        const referrer = info.referrer ? sanitizeUrl(info.referrer) : null;
+        if (referrer && referrer.length > MAX_URL_LENGTH)
+            return null;
+        return {
+            type: 'ai_referral',
+            url,
+            ...(referrer && { referrer }),
+            ...(status !== undefined && { status }),
+            occurred_at
+        };
+    }
+    return null;
+}
+/** Reads the client IP from the headers that hosts and CDNs set. */
+export function clientIpFromHeaders(headers) {
+    const direct = headers.get('cf-connecting-ip') ??
+        headers.get('true-client-ip') ??
+        headers.get('x-real-ip');
+    if (direct)
+        return direct.trim();
+    const forwarded = headers.get('x-forwarded-for');
+    return forwarded ? (forwarded.split(',')[0]?.trim() ?? null) : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { AI_AGENTS, AI_APPS, type AiAgent, type AiAgentPurpose, type AiApp, type AiAppId, type AiOperator } from './catalog.js';
+export { matchAiAgent, matchAiApp, sanitizeUrl } from './classify.js';
+export { clientIpFromHeaders, MAX_URL_LENGTH, toAiTrafficEvent, type AiReferralEvent, type AiTrafficEvent, type AiTrafficRequestInfo, type BotVisitEvent } from './events.js';
+export { createAiTraffic, DEFAULT_ENDPOINT, MAX_EVENTS_PER_REQUEST, MAX_REQUEST_BYTES, type AiTrafficBatchOptions, type AiTrafficOptions, type AiTrafficTracker } from './client.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { AI_AGENTS, AI_APPS } from './catalog.js';
+export { matchAiAgent, matchAiApp, sanitizeUrl } from './classify.js';
+export { clientIpFromHeaders, MAX_URL_LENGTH, toAiTrafficEvent } from './events.js';
+export { createAiTraffic, DEFAULT_ENDPOINT, MAX_EVENTS_PER_REQUEST, MAX_REQUEST_BYTES } from './client.js';

package/package.json

@@ -1,6 +1,88 @@
 {
-  "name": "@aranx/ai-analytics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@aranx/ai-analytics",
+    "version": "0.1.0",
+    "description": "Track AI search bots and visitors from AI apps on your site with Aranx.",
+    "license": "MIT",
+    "type": "module",
+    "sideEffects": false,
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/aranx-ai/blog-empire.git",
+        "directory": "packages/ai-analytics"
+    },
+    "homepage": "https://aranx.com",
+    "keywords": [
+        "aranx",
+        "ai",
+        "chatgpt",
+        "perplexity",
+        "claude",
+        "bots",
+        "analytics",
+        "geo"
+    ],
+    "engines": {
+        "node": ">=20.19"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./next": {
+            "types": "./dist/adapters/next.d.ts",
+            "default": "./dist/adapters/next.js"
+        },
+        "./fetch": {
+            "types": "./dist/adapters/fetch.d.ts",
+            "default": "./dist/adapters/fetch.js"
+        },
+        "./hono": {
+            "types": "./dist/adapters/hono.d.ts",
+            "default": "./dist/adapters/hono.js"
+        },
+        "./express": {
+            "types": "./dist/adapters/express.d.ts",
+            "default": "./dist/adapters/express.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "typesVersions": {
+        "*": {
+            "next": [
+                "./dist/adapters/next.d.ts"
+            ],
+            "fetch": [
+                "./dist/adapters/fetch.d.ts"
+            ],
+            "hono": [
+                "./dist/adapters/hono.d.ts"
+            ],
+            "express": [
+                "./dist/adapters/express.d.ts"
+            ]
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "rm -rf dist && tsc -p tsconfig.build.json",
+        "tsc": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage"
+    },
+    "devDependencies": {
+        "@types/node": "^22.15.29",
+        "@vitest/coverage-v8": "^5.0.5",
+        "typescript": "^5.7.2",
+        "vitest": "^5.0.5"
+    }
+}