apptvty 0.1.2

package/README.md

@@ -0,0 +1,537 @@
+# apptvty
+
+**AI traffic analytics and Agent Experience Optimization (AEO) for Node.js websites.**
+
+Apptvty makes your website visible to, and queryable by, AI agents — the crawlers and language models (GPTBot, ClaudeBot, Perplexity, etc.) that are increasingly the primary consumers of web content.
+
+- **Detects and classifies AI traffic** that standard analytics tools miss entirely
+- **Exposes a `/query` endpoint** so AI agents can get structured, sourced answers from your site
+- **Earns USDC** for your site when sponsored ads are served in query responses
+- **Two lines to integrate** into an existing Next.js or Express app
+
+```
+npm install apptvty
+```
+
+Node.js >= 18 required.
+
+---
+
+## Quick start
+
+### Next.js (App Router)
+
+**Step 1 — Log all traffic**
+
+```typescript
+// middleware.ts
+import { withApptvty } from 'apptvty/nextjs';
+
+export default withApptvty({
+  apiKey: process.env.APPTVTY_API_KEY!,
+  siteId: process.env.APPTVTY_SITE_ID!,
+});
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+**Step 2 — Expose the query endpoint**
+
+```typescript
+// app/query/route.ts
+import { createNextjsQueryHandler } from 'apptvty/nextjs';
+
+export const GET = createNextjsQueryHandler({
+  apiKey: process.env.APPTVTY_API_KEY!,
+  siteId: process.env.APPTVTY_SITE_ID!,
+});
+```
+
+**That's it.** Every request is now logged, AI crawlers are classified, and AI agents can query your site at `https://yoursite.com/query?q=your+question`.
+
+---
+
+### Express
+
+```typescript
+import express from 'express';
+import { createExpressMiddleware, createExpressQueryHandler } from 'apptvty/express';
+
+const app = express();
+const config = {
+  apiKey: process.env.APPTVTY_API_KEY!,
+  siteId: process.env.APPTVTY_SITE_ID!,
+};
+
+// Log all requests
+app.use(createExpressMiddleware(config));
+
+// Expose the query endpoint
+app.get('/query', createExpressQueryHandler(config));
+```
+
+---
+
+### CLI setup (humans and agents)
+
+The fastest way to get credentials and scaffold files:
+
+```bash
+# Interactive (human)
+npx apptvty init
+
+# Non-interactive (agent / CI) — prints JSON to stdout
+npx apptvty init --domain mysite.com --framework nextjs --non-interactive
+```
+
+Trigger a re-crawl after publishing new content:
+
+```bash
+# Reindex your site (reads APPTVTY_SITE_ID and APPTVTY_API_KEY from .env.local / .env)
+npx apptvty migrate
+```
+
+CLI commands:
+
+| Command | Description |
+|---------|-------------|
+| `init` | Register site and scaffold integration files (default) |
+| `migrate` | Trigger immediate re-crawl/reindex of your site |
+
+CLI flags:
+
+| Flag | Description |
+|------|-------------|
+| `--domain` | Your site's domain, e.g. `mysite.com` (init only) |
+| `--framework` | `nextjs`, `express`, or `other` (init only, auto-detected) |
+| `--non-interactive` | No prompts; JSON output for scripting/agents |
+| `--api-url` | Override API base URL (staging / self-hosted) |
+
+**Agent-mode JSON output:**
+```json
+{
+  "site_id": "site_abc123",
+  "api_key": "ak_live_...",
+  "company_id": "co_xyz...",
+  "wallet_address": "0x...",
+  "dashboard_url": "https://app.apptvty.com/claim?token=...",
+  "env_file": ".env.local",
+  "env_vars": {
+    "APPTVTY_SITE_ID": "site_abc123",
+    "APPTVTY_API_KEY": "ak_live_..."
+  }
+}
+```
+
+The CLI writes credentials to `.env.local` (Next.js) or `.env` (Express/other) and scaffolds `middleware.ts` and `app/query/route.ts` if they do not already exist.
+
+---
+
+## Package exports
+
+| Import | Contents |
+|--------|----------|
+| `apptvty` | Core client, logger, crawler detector, query handler (framework-agnostic) |
+| `apptvty/nextjs` | Next.js App Router middleware and route handler |
+| `apptvty/express` | Express/Connect middleware and route handler |
+| `apptvty/setup` | `register()` and `migrate()` for programmatic setup and reindex |
+
+---
+
+## Configuration
+
+All middleware and handler functions accept an `ApptvtyConfig` object:
+
+```typescript
+interface ApptvtyConfig {
+  apiKey: string;          // Required. Your site's API key (ak_...)
+  siteId: string;          // Required. Your site ID from the dashboard
+  baseUrl?: string;        // Optional. Uses APPTVTY_API_URL env if set.
+  batchSize?: number;      // Default: 50  — logs per flush
+  flushInterval?: number;  // Default: 5000 — ms between auto-flushes
+  debug?: boolean;         // Default: false — log errors to console
+  queryPath?: string;      // Default: '/query' — path of AEO endpoint
+}
+```
+
+Set these from environment variables so credentials are never in source code:
+
+```
+APPTVTY_API_KEY=ak_live_...
+APPTVTY_SITE_ID=site_...
+APPTVTY_API_URL=https://api.apptvty.com   # Optional. Default is api.apptvty.com; override for self-hosted only.
+```
+
+See [.env.example](.env.example) for a copy-paste template.
+
+**Production:** The SDK uses **https://api.apptvty.com** by default. You do not need to set `APPTVTY_API_URL` for production.
+
+### Using the SDK with a self-hosted backend
+
+Only if you run **apptvty-backend** yourself (e.g. Serverless in your AWS account), point the SDK at that API:
+
+1. **Deploy the backend** (from the backend repo):
+   ```bash
+   cd apptvty-backend
+   npx sls deploy --stage dev
+   ```
+2. **Get the API URL** from the stack output:
+   ```bash
+   npx sls info --stage dev
+   ```
+   Use the **ApiGatewayRestApiUrl** (e.g. `https://xxxx.execute-api.us-west-2.amazonaws.com/dev`).
+3. **Override the default (api.apptvty.com)** in one of two ways:
+   - **Environment:** Set `APPTVTY_API_URL` to that URL (no trailing slash).
+   - **In code:** Pass `baseUrl` (or `apiUrl` for `register`/`migrate`).
+
+---
+
+## The query endpoint
+
+When an AI agent visits `https://yoursite.com/query`, the SDK responds with a self-describing discovery page so the agent knows how to use it:
+
+```json
+{
+  "version": "1.0",
+  "endpoint": "https://yoursite.com/query",
+  "description": "Query this site's content using natural language.",
+  "usage": {
+    "method": "GET",
+    "parameters": {
+      "q": { "type": "string", "required": true, "description": "Natural language question" },
+      "lang": { "type": "string", "required": false, "description": "Preferred language (ISO 639-1)" }
+    },
+    "example": "https://yoursite.com/query?q=What+does+this+site+do"
+  },
+  "capabilities": ["rag", "sponsored_ads"],
+  "rate_limit": "60 requests per minute"
+}
+```
+
+When called with `?q=<question>`:
+
+```json
+{
+  "success": true,
+  "version": "1.0",
+  "query": "What does this site do?",
+  "answer": "Apptvty is an AI traffic analytics platform ...",
+  "sources": [
+    {
+      "url": "https://yoursite.com/about",
+      "title": "About Apptvty",
+      "snippet": "Apptvty logs and classifies AI crawler traffic ...",
+      "relevance": 0.94
+    }
+  ],
+  "confidence": 0.91,
+  "sponsored": {
+    "label": "Sponsored",
+    "text": "Get deeper AI analytics with AEO Pro — 14-day free trial",
+    "url": "https://...",
+    "advertiser": "AEO Pro",
+    "impression_id": "imp_..."
+  },
+  "metadata": {
+    "request_id": "req_...",
+    "response_time_ms": 340,
+    "tokens_used": 420,
+    "site_id": "site_...",
+    "timestamp": "2026-03-06T12:00:00.000Z"
+  }
+}
+```
+
+The `sponsored` field is present only when ads are enabled for your site and a matching ad exists. Ads are clearly labeled and serve as a revenue stream for site owners — no action required by the agent beyond passing the field through to the end user.
+
+**Error response:**
+```json
+{
+  "success": false,
+  "error": {
+    "code": "QUERY_TOO_LONG",
+    "message": "Query exceeds the 500-character limit.",
+    "request_id": "req_...",
+    "timestamp": "2026-03-06T12:00:00.000Z"
+  }
+}
+```
+
+Response headers always include:
+- `Content-Type: application/json`
+- `Cache-Control: no-store`
+- `X-Robots-Tag: noindex`
+
+---
+
+## Analytics for coding agents
+
+The SDK exposes methods so coding agents (e.g. Cursor, Claude Code) can fetch logs, activity, and errors without human intervention — similar to how `aws logs tail` works for AWS CLI.
+
+```typescript
+import { ApptvtyClient } from 'apptvty';
+
+const client = new ApptvtyClient({
+  apiKey: process.env.APPTVTY_API_KEY!,
+  siteId: process.env.APPTVTY_SITE_ID!,
+});
+
+// 30-day overview
+const stats = await client.getSiteStats();
+console.log(`AI traffic: ${stats.ai_percentage}%`);
+
+// Recent activity (last hour)
+const { activity } = await client.getSiteActivity(20);
+activity.forEach(a => console.log(a.path, a.crawler_type, a.status_code));
+
+// Recent agent queries
+const { queries } = await client.getSiteQueries(10);
+
+// Crawler breakdown
+const { crawlers } = await client.getSiteCrawlers(7);
+
+// Daily stats
+const { stats: daily } = await client.getSiteDailyStats(30);
+
+// Wallet balance
+const wallet = await client.getSiteWallet();
+```
+
+| Method | Returns |
+|--------|---------|
+| `getSiteStats()` | 30-day overview (requests, AI %, crawlers, queries) |
+| `getSiteDailyStats(days?)` | Per-day breakdown |
+| `getSiteActivity(limit?)` | Recent requests (path, crawler, status) |
+| `getSiteQueries(limit?)` | Recent agent queries |
+| `getSiteCrawlers(days?)` | Crawler type breakdown |
+| `getSiteWallet()` | Balance, earnings, spend |
+
+---
+
+## Crawler detection
+
+The SDK identifies 50+ AI crawlers by user-agent string. Access detection directly:
+
+```typescript
+import { detectCrawler, getKnownCrawlerNames } from 'apptvty';
+
+const info = detectCrawler('GPTBot/1.1');
+// {
+//   isAi: true,
+//   name: 'GPTBot',
+//   organization: 'OpenAI',
+//   confidence: 0.95,
+//   detectionMethod: 'exact_match'
+// }
+
+const names = getKnownCrawlerNames();
+// ['GPTBot', 'ClaudeBot', 'PerplexityBot', 'BingBot', ...]
+```
+
+**`CrawlerInfo` fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isAi` | `boolean` | Whether the traffic is from an AI/LLM system |
+| `name` | `string \| null` | Crawler name, e.g. `"GPTBot"` |
+| `organization` | `string \| null` | Organization, e.g. `"OpenAI"` |
+| `confidence` | `number` | Detection certainty, 0.0 – 1.0 |
+| `detectionMethod` | `string` | `exact_match` / `pattern_match` / `heuristic` / `none` |
+
+**Crawlers recognized (partial list):** GPTBot, OpenAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-Web, Anthropic-AI, Google-Extended, GoogleOther, Bingbot, PerplexityBot, YouBot, DuckDuckBot, Meta-ExternalAgent, LinkedInBot, AppleBot, TwitterBot, CohereAI, AI2Bot, MistralBot.
+
+---
+
+## Programmatic registration
+
+For agents and scripts that need to register a site without the CLI:
+
+```typescript
+import { register, RegistrationError } from 'apptvty/setup';
+
+try {
+  const result = await register({
+    domain: 'mysite.com',
+    framework: 'nextjs',   // 'nextjs' | 'express' | 'other'
+    agentId: 'my-agent',   // optional — analytics on which agent registered
+  });
+
+  console.log(result.apiKey);        // 'ak_live_...'
+  console.log(result.siteId);        // 'site_...'
+  console.log(result.walletAddress); // '0x...' or null
+  console.log(result.dashboardUrl);  // Dashboard claim link (valid 30 days)
+  console.log(result.setup.envVars); // { APPTVTY_SITE_ID, APPTVTY_API_KEY }
+
+} catch (err) {
+  if (err instanceof RegistrationError) {
+    // err.code: 'DOMAIN_TAKEN' | 'REGISTRATION_FAILED' | ...
+    console.error(err.code, err.message);
+  }
+}
+```
+
+**`RegisterOptions`:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `domain` | `string` | Yes | Site domain, e.g. `mysite.com` |
+| `framework` | `string` | No | `nextjs`, `express`, or `other` |
+| `agentId` | `string` | No | Identifies the registering agent (for analytics) |
+| `apiUrl` | `string` | No | Override API base URL for staging/self-hosted |
+
+**`RegisterResult`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `siteId` | `string` | Site identifier |
+| `apiKey` | `string` | API key for SDK config |
+| `companyId` | `string` | Company identifier |
+| `walletAddress` | `string \| null` | Crossmint wallet for USDC earnings |
+| `dashboardUrl` | `string` | Dashboard claim link (valid 30 days) |
+| `claimTokenExpiresAt` | `string` | ISO timestamp of link expiry |
+| `setup.envVars` | `object` | Env vars to write to your `.env` file |
+| `setup.files` | `object \| undefined` | Optional scaffold file contents |
+
+Registration is idempotent per domain. Registering the same domain twice throws `RegistrationError` with `code: 'DOMAIN_TAKEN'`.
+
+### Programmatic migrate (reindex)
+
+Trigger an immediate re-crawl after publishing new content:
+
+```typescript
+import { migrate, MigrateError } from 'apptvty/setup';
+
+try {
+  const result = await migrate({
+    siteId: process.env.APPTVTY_SITE_ID!,
+    apiKey: process.env.APPTVTY_API_KEY!,
+    apiUrl: 'https://api.apptvty.com',  // optional — for staging/self-hosted
+  });
+  console.log(result.message); // "Reindex started. Your site content will be updated within a few minutes."
+} catch (err) {
+  if (err instanceof MigrateError) {
+    console.error(err.code, err.message);
+  }
+}
+```
+
+The crawl runs asynchronously; the endpoint returns 202 immediately.
+
+---
+
+## Advanced: framework-agnostic usage
+
+Use `ApptvtyClient` and `RequestLogger` directly for custom frameworks:
+
+```typescript
+import { ApptvtyClient, RequestLogger, detectCrawler, createQueryHandler } from 'apptvty';
+
+const config = { apiKey: 'ak_...', siteId: 'site_...' };
+const client = new ApptvtyClient(config);
+const logger = new RequestLogger(client, config);
+
+// In your request handler:
+const crawlerInfo = detectCrawler(req.headers['user-agent'] ?? '');
+logger.enqueue({
+  site_id: config.siteId,
+  timestamp: new Date().toISOString(),
+  method: req.method,
+  path: req.url,
+  status_code: res.statusCode,
+  response_time_ms: elapsedMs,
+  ip_address: req.socket.remoteAddress ?? '',
+  user_agent: req.headers['user-agent'] ?? '',
+  referer: req.headers.referer ?? null,
+  is_ai_crawler: crawlerInfo.isAi,
+  crawler_type: crawlerInfo.name,
+  crawler_organization: crawlerInfo.organization,
+  confidence_score: crawlerInfo.confidence,
+});
+
+// Flush on shutdown
+process.on('SIGTERM', () => logger.flush());
+```
+
+---
+
+## Request logging behavior
+
+- Logs are **batched in memory** and flushed every `flushInterval` ms (default 5s) or when `batchSize` entries accumulate (default 50)
+- Logging is **non-blocking** — failures never propagate to the request handler
+- The logger automatically flushes on `SIGTERM`, `SIGINT`, and `beforeExit`
+- The flush timer is **unreferenced** — it will not keep a process alive after all other work is done
+
+**Paths skipped by middleware (never logged):**
+- `/_next/` — Next.js build assets
+- `/api/_*` — Internal Next.js API routes
+- `/favicon.ico`
+- Static file extensions: `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.ico`, `.woff`, `.woff2`, `.ttf`, `.css`, `.js.map`
+
+---
+
+## Analytics dashboard
+
+Visit your `dashboardUrl` after registration to:
+- View AI vs human traffic split over time
+- See which crawlers are visiting and how often
+- Browse agent queries and the answers served
+- Track USDC earnings from sponsored ads
+- Manage API keys and site settings
+
+The link is valid for 30 days. Add an email address in the dashboard to establish a permanent login.
+
+---
+
+## Testing
+
+```bash
+npm test           # Unit + integration (hits real dev API)
+npm run test:unit  # Unit tests only (mocked API)
+npm run test:integration  # Integration tests against deployed dev API
+```
+
+**Integration tests** use **https://api.apptvty.com** by default: they register a new test site, send real logs, and verify analytics and migrate. No env vars required. Needs network access.
+
+---
+
+## Publishing the SDK (npm)
+
+The SDK is an **npm package**. “Deploy” means publishing to the registry so users can `npm install apptvty`.
+
+**Prerequisites**
+
+- npm account ([npmjs.com](https://www.npmjs.com/signup))
+- Logged in: `npm login`
+
+**Release steps**
+
+1. **Bump version** in `package.json` (or use `npm version`):
+   ```bash
+   npm version patch   # 0.1.0 → 0.1.1
+   # or: npm version minor   # 0.1.0 → 0.2.0
+   ```
+
+2. **Run tests** (optional but recommended):
+   ```bash
+   npm run test:unit
+   npm run test:integration   # uses api.apptvty.com
+   ```
+
+3. **Publish**:
+   ```bash
+   npm publish
+   ```
+   `prepublishOnly` runs `npm run build && npm run typecheck` automatically before the package is uploaded.
+
+For a **scoped package** (e.g. `@apptvty/sdk`), make sure `package.json` has `"name": "@apptvty/sdk"` and use:
+```bash
+npm publish --access public
+```
+
+---
+
+## License
+
+MIT

package/dist/chunk-RGUS6IL6.mjs

@@ -0,0 +1,87 @@
+import {
+  ApptvtyClient,
+  RequestLogger,
+  createQueryHandler,
+  detectCrawler,
+  getClientIp
+} from "./chunk-WATTAPBA.mjs";
+
+// src/middleware/express.ts
+var instances = /* @__PURE__ */ new Map();
+function getInstance(config) {
+  const key = config.apiKey;
+  if (!instances.has(key)) {
+    const client = new ApptvtyClient(config);
+    const logger = new RequestLogger(client, config);
+    instances.set(key, { client, logger });
+  }
+  return instances.get(key);
+}
+function createExpressMiddleware(config) {
+  const { logger } = getInstance(config);
+  return function apptvtyLogger(req, res, next) {
+    const startMs = Date.now();
+    const userAgent = req.headers["user-agent"] ?? "";
+    const crawlerInfo = detectCrawler(userAgent);
+    const path = req.url ?? "/";
+    res.on("finish", () => {
+      if (shouldSkip(path)) return;
+      const entry = {
+        site_id: config.siteId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        method: req.method ?? "GET",
+        path,
+        status_code: res.statusCode,
+        response_time_ms: Date.now() - startMs,
+        ip_address: getClientIp(req.headers),
+        user_agent: userAgent,
+        referer: req.headers["referer"] ?? null,
+        is_ai_crawler: crawlerInfo.isAi,
+        crawler_type: crawlerInfo.name,
+        crawler_organization: crawlerInfo.organization,
+        confidence_score: crawlerInfo.confidence
+      };
+      logger.enqueue(entry);
+    });
+    next();
+  };
+}
+function createExpressQueryHandler(config) {
+  const { client } = getInstance(config);
+  const handleQuery = createQueryHandler(client, config);
+  return async function queryHandler(req, res) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const q = url.searchParams.get("q");
+    const lang = url.searchParams.get("lang");
+    const surfaceAds = parseBoolParam(url.searchParams.get("surface_ads"), true);
+    const aiCrawler = parseBoolParam(url.searchParams.get("ai_crawler"), false);
+    const userAgent = req.headers["user-agent"] ?? "";
+    const result = await handleQuery({
+      query: q,
+      lang,
+      surface_ads: surfaceAds,
+      ai_crawler: aiCrawler,
+      userAgent,
+      ipAddress: getClientIp(req.headers),
+      requestUrl: url.toString()
+    });
+    for (const [key, value] of Object.entries(result.headers)) {
+      res.setHeader(key, value);
+    }
+    res.statusCode = result.status;
+    res.end(JSON.stringify(result.body));
+  };
+}
+function parseBoolParam(value, defaultValue) {
+  if (value === null) return defaultValue;
+  return value === "1" || value === "true" || value === "yes";
+}
+function shouldSkip(path) {
+  return path.startsWith("/_next/") || /\.(svg|png|jpg|jpeg|gif|webp|ico|woff2?|ttf|css|js\.map)$/.test(path);
+}
+
+export {
+  createExpressMiddleware,
+  createExpressQueryHandler
+};
+//# sourceMappingURL=chunk-RGUS6IL6.mjs.map

package/dist/chunk-RGUS6IL6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware/express.ts"],"sourcesContent":["/**\n * Express / Node.js integration for the Apptvty SDK.\n *\n * Usage:\n *\n *   import express from 'express';\n *   import { createExpressMiddleware, createExpressQueryHandler } from 'apptvty/express';\n *\n *   const app = express();\n *   const config = { apiKey: 'ak_...', siteId: 'site_...' };\n *\n *   // 1. Log all traffic\n *   app.use(createExpressMiddleware(config));\n *\n *   // 2. Mount the AEO query page\n *   app.get('/query', createExpressQueryHandler(config));\n *\n * Works with any Connect-compatible framework (Express, Fastify via @fastify/express, etc.)\n */\n\nimport type { IncomingMessage, ServerResponse } from 'node:http';\nimport { ApptvtyClient } from '../client.js';\nimport { detectCrawler } from '../crawler.js';\nimport { RequestLogger, getClientIp } from '../logger.js';\nimport { createQueryHandler } from '../query-handler.js';\nimport type { ApptvtyConfig, RequestLogEntry } from '../types.js';\n\nexport type ConnectMiddleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: (err?: unknown) => void,\n) => void;\n\nexport type ConnectHandler = (\n  req: IncomingMessage,\n  res: ServerResponse,\n) => void | Promise<void>;\n\n// ─── Shared singleton instances per config ────────────────────────────────────\n\nconst instances = new Map<string, { client: ApptvtyClient; logger: RequestLogger }>();\n\nfunction getInstance(config: ApptvtyConfig) {\n  const key = config.apiKey;\n  if (!instances.has(key)) {\n    const client = new ApptvtyClient(config);\n    const logger = new RequestLogger(client, config);\n    instances.set(key, { client, logger });\n  }\n  return instances.get(key)!;\n}\n\n// ─── Traffic logging middleware ───────────────────────────────────────────────\n\n/**\n * Express middleware that logs every request to Apptvty.\n * Captures: method, path, status, response time, user-agent, IP, crawler classification.\n *\n * Mount this before your routes so all traffic is captured.\n *\n * @example\n * app.use(createExpressMiddleware({ apiKey: 'ak_...', siteId: 'site_...' }));\n */\nexport function createExpressMiddleware(config: ApptvtyConfig): ConnectMiddleware {\n  const { logger } = getInstance(config);\n\n  return function apptvtyLogger(req, res, next) {\n    const startMs = Date.now();\n    const userAgent = req.headers['user-agent'] ?? '';\n    const crawlerInfo = detectCrawler(userAgent);\n    const path = req.url ?? '/';\n\n    // Intercept response finish to capture status code and timing\n    res.on('finish', () => {\n      if (shouldSkip(path)) return;\n\n      const entry: RequestLogEntry = {\n        site_id: config.siteId,\n        timestamp: new Date().toISOString(),\n        method: req.method ?? 'GET',\n        path,\n        status_code: res.statusCode,\n        response_time_ms: Date.now() - startMs,\n        ip_address: getClientIp(req.headers as Record<string, string | string[] | undefined>),\n        user_agent: userAgent,\n        referer: (req.headers['referer'] as string) ?? null,\n        is_ai_crawler: crawlerInfo.isAi,\n        crawler_type: crawlerInfo.name,\n        crawler_organization: crawlerInfo.organization,\n        confidence_score: crawlerInfo.confidence,\n      };\n\n      logger.enqueue(entry);\n    });\n\n    next();\n  };\n}\n\n// ─── Query endpoint handler ───────────────────────────────────────────────────\n\n/**\n * Express route handler for the AEO query endpoint.\n *\n * Mount this at the path configured in your dashboard (default: /query).\n *\n * @example\n * app.get('/query', createExpressQueryHandler({ apiKey: 'ak_...', siteId: 'site_...' }));\n */\nexport function createExpressQueryHandler(config: ApptvtyConfig): ConnectHandler {\n  const { client } = getInstance(config);\n  const handleQuery = createQueryHandler(client, config);\n\n  return async function queryHandler(req, res) {\n    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);\n    const q = url.searchParams.get('q');\n    const lang = url.searchParams.get('lang');\n    const surfaceAds = parseBoolParam(url.searchParams.get('surface_ads'), true);\n    const aiCrawler = parseBoolParam(url.searchParams.get('ai_crawler'), false);\n    const userAgent = req.headers['user-agent'] ?? '';\n\n    const result = await handleQuery({\n      query: q,\n      lang,\n      surface_ads: surfaceAds,\n      ai_crawler: aiCrawler,\n      userAgent,\n      ipAddress: getClientIp(req.headers as Record<string, string | string[] | undefined>),\n      requestUrl: url.toString(),\n    });\n\n    for (const [key, value] of Object.entries(result.headers)) {\n      res.setHeader(key, value);\n    }\n    res.statusCode = result.status;\n    res.end(JSON.stringify(result.body));\n  };\n}\n\n// ─── Helpers ──────────────────────────────────────────────────────────────────\n\nfunction parseBoolParam(value: string | null, defaultValue: boolean): boolean {\n  if (value === null) return defaultValue;\n  return value === '1' || value === 'true' || value === 'yes';\n}\n\nfunction shouldSkip(path: string): boolean {\n  return (\n    path.startsWith('/_next/') ||\n    /\\.(svg|png|jpg|jpeg|gif|webp|ico|woff2?|ttf|css|js\\.map)$/.test(path)\n  );\n}\n"],"mappings":";;;;;;;;;AAwCA,IAAM,YAAY,oBAAI,IAA8D;AAEpF,SAAS,YAAY,QAAuB;AAC1C,QAAM,MAAM,OAAO;AACnB,MAAI,CAAC,UAAU,IAAI,GAAG,GAAG;AACvB,UAAM,SAAS,IAAI,cAAc,MAAM;AACvC,UAAM,SAAS,IAAI,cAAc,QAAQ,MAAM;AAC/C,cAAU,IAAI,KAAK,EAAE,QAAQ,OAAO,CAAC;AAAA,EACvC;AACA,SAAO,UAAU,IAAI,GAAG;AAC1B;AAaO,SAAS,wBAAwB,QAA0C;AAChF,QAAM,EAAE,OAAO,IAAI,YAAY,MAAM;AAErC,SAAO,SAAS,cAAc,KAAK,KAAK,MAAM;AAC5C,UAAM,UAAU,KAAK,IAAI;AACzB,UAAM,YAAY,IAAI,QAAQ,YAAY,KAAK;AAC/C,UAAM,cAAc,cAAc,SAAS;AAC3C,UAAM,OAAO,IAAI,OAAO;AAGxB,QAAI,GAAG,UAAU,MAAM;AACrB,UAAI,WAAW,IAAI,EAAG;AAEtB,YAAM,QAAyB;AAAA,QAC7B,SAAS,OAAO;AAAA,QAChB,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,QAClC,QAAQ,IAAI,UAAU;AAAA,QACtB;AAAA,QACA,aAAa,IAAI;AAAA,QACjB,kBAAkB,KAAK,IAAI,IAAI;AAAA,QAC/B,YAAY,YAAY,IAAI,OAAwD;AAAA,QACpF,YAAY;AAAA,QACZ,SAAU,IAAI,QAAQ,SAAS,KAAgB;AAAA,QAC/C,eAAe,YAAY;AAAA,QAC3B,cAAc,YAAY;AAAA,QAC1B,sBAAsB,YAAY;AAAA,QAClC,kBAAkB,YAAY;AAAA,MAChC;AAEA,aAAO,QAAQ,KAAK;AAAA,IACtB,CAAC;AAED,SAAK;AAAA,EACP;AACF;AAYO,SAAS,0BAA0B,QAAuC;AAC/E,QAAM,EAAE,OAAO,IAAI,YAAY,MAAM;AACrC,QAAM,cAAc,mBAAmB,QAAQ,MAAM;AAErD,SAAO,eAAe,aAAa,KAAK,KAAK;AAC3C,UAAM,MAAM,IAAI,IAAI,IAAI,OAAO,KAAK,UAAU,IAAI,QAAQ,QAAQ,WAAW,EAAE;AAC/E,UAAM,IAAI,IAAI,aAAa,IAAI,GAAG;AAClC,UAAM,OAAO,IAAI,aAAa,IAAI,MAAM;AACxC,UAAM,aAAa,eAAe,IAAI,aAAa,IAAI,aAAa,GAAG,IAAI;AAC3E,UAAM,YAAY,eAAe,IAAI,aAAa,IAAI,YAAY,GAAG,KAAK;AAC1E,UAAM,YAAY,IAAI,QAAQ,YAAY,KAAK;AAE/C,UAAM,SAAS,MAAM,YAAY;AAAA,MAC/B,OAAO;AAAA,MACP;AAAA,MACA,aAAa;AAAA,MACb,YAAY;AAAA,MACZ;AAAA,MACA,WAAW,YAAY,IAAI,OAAwD;AAAA,MACnF,YAAY,IAAI,SAAS;AAAA,IAC3B,CAAC;AAED,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,OAAO,GAAG;AACzD,UAAI,UAAU,KAAK,KAAK;AAAA,IAC1B;AACA,QAAI,aAAa,OAAO;AACxB,QAAI,IAAI,KAAK,UAAU,OAAO,IAAI,CAAC;AAAA,EACrC;AACF;AAIA,SAAS,eAAe,OAAsB,cAAgC;AAC5E,MAAI,UAAU,KAAM,QAAO;AAC3B,SAAO,UAAU,OAAO,UAAU,UAAU,UAAU;AACxD;AAEA,SAAS,WAAW,MAAuB;AACzC,SACE,KAAK,WAAW,SAAS,KACzB,4DAA4D,KAAK,IAAI;AAEzE;","names":[]}