apptvty 0.1.2

package/dist/chunk-XOWRKLFM.mjs

@@ -0,0 +1,150 @@
+import {
+  ApptvtyClient,
+  RequestLogger,
+  createQueryHandler,
+  detectCrawler,
+  getClientIp
+} from "./chunk-WATTAPBA.mjs";
+
+// src/middleware/nextjs.ts
+import { NextResponse } from "next/server";
+function headersToRecord(h) {
+  const entries = h.entries();
+  return Object.fromEntries(Array.from(entries));
+}
+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 withApptvty(config, next) {
+  const { client, logger } = getInstance(config);
+  const queryPath = config.queryPath ?? "/query";
+  return async function apptvtyMiddleware(request) {
+    const startMs = Date.now();
+    const userAgent = request.headers.get("user-agent") ?? "";
+    const crawlerInfo = detectCrawler(userAgent);
+    const aiCrawlerParam = parseBoolParam(request.nextUrl.searchParams.get("ai_crawler"), false);
+    const isCrawler = crawlerInfo.isAi || aiCrawlerParam;
+    let response;
+    try {
+      response = next ? await next(request) : NextResponse.next();
+    } catch (err) {
+      throw err;
+    }
+    const responseTimeMs = Date.now() - startMs;
+    const { pathname } = request.nextUrl;
+    if (shouldSkip(pathname)) {
+      return response;
+    }
+    const headers = headersToRecord(request.headers);
+    const entry = {
+      site_id: config.siteId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      method: request.method,
+      path: pathname,
+      status_code: response.status,
+      response_time_ms: responseTimeMs,
+      ip_address: getClientIp(headers),
+      user_agent: userAgent,
+      referer: request.headers.get("referer"),
+      is_ai_crawler: crawlerInfo.isAi,
+      crawler_type: crawlerInfo.name,
+      crawler_organization: crawlerInfo.organization,
+      confidence_score: crawlerInfo.confidence
+    };
+    logger.enqueue(entry);
+    if (isCrawler && response.ok && !pathname.startsWith(queryPath)) {
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("text/html")) {
+        try {
+          const modified = await injectAdsIntoHtml(response, client, config.siteId, pathname);
+          if (modified) return modified;
+        } catch (err) {
+          if (config.debug) console.warn("[apptvty] Ad injection failed:", err);
+        }
+      }
+    }
+    return response;
+  };
+}
+function createNextjsQueryHandler(config) {
+  const { client } = getInstance(config);
+  const handleQuery = createQueryHandler(client, config);
+  return async function GET(request) {
+    const { searchParams } = request.nextUrl;
+    const q = searchParams.get("q");
+    const lang = searchParams.get("lang");
+    const surfaceAds = parseBoolParam(searchParams.get("surface_ads"), true);
+    const aiCrawler = parseBoolParam(searchParams.get("ai_crawler"), false);
+    const userAgent = request.headers.get("user-agent") ?? "";
+    const headers = headersToRecord(request.headers);
+    const result = await handleQuery({
+      query: q,
+      lang,
+      surface_ads: surfaceAds,
+      ai_crawler: aiCrawler,
+      userAgent,
+      ipAddress: getClientIp(headers),
+      requestUrl: request.url
+    });
+    return NextResponse.json(result.body, {
+      status: result.status,
+      headers: result.headers
+    });
+  };
+}
+var AD_INJECTION_MARKER = "<!-- apptvty-sponsored -->";
+function buildAdBlock(ads) {
+  const items = ads.map(
+    (ad) => `<li><a href="${escapeHtml(ad.url)}" rel="nofollow">${escapeHtml(ad.text)}</a> <small>\u2014 ${escapeHtml(ad.advertiser)}</small></li>`
+  ).join("\n");
+  return `
+<section aria-label="Sponsored" data-sponsored ${AD_INJECTION_MARKER}>
+  <h3>Sponsored</h3>
+  <ul>${items}</ul>
+</section>`;
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+async function injectAdsIntoHtml(response, client, siteId, pathname) {
+  const html = await response.text();
+  if (!html || html.includes(AD_INJECTION_MARKER)) return null;
+  const pageAds = await client.getAdsForPage({ site_id: siteId, page_path: pathname });
+  if (!pageAds.ads || pageAds.ads.length === 0) return null;
+  const adBlock = buildAdBlock(pageAds.ads);
+  let modified;
+  if (html.includes("</body>")) {
+    modified = html.replace("</body>", `${adBlock}
+</body>`);
+  } else if (html.includes("</html>")) {
+    modified = html.replace("</html>", `${adBlock}
+</html>`);
+  } else {
+    modified = html + adBlock;
+  }
+  return new NextResponse(modified, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: new Headers(response.headers)
+  });
+}
+function parseBoolParam(value, defaultValue) {
+  if (value === null) return defaultValue;
+  return value === "1" || value === "true" || value === "yes";
+}
+function shouldSkip(pathname) {
+  return pathname.startsWith("/_next/") || pathname.startsWith("/api/_") || pathname === "/favicon.ico" || /\.(svg|png|jpg|jpeg|gif|webp|ico|woff2?|ttf|css|js\.map)$/.test(pathname);
+}
+
+export {
+  withApptvty,
+  createNextjsQueryHandler
+};
+//# sourceMappingURL=chunk-XOWRKLFM.mjs.map

package/dist/chunk-XOWRKLFM.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware/nextjs.ts"],"sourcesContent":["/**\n * Next.js App Router integration for the Apptvty SDK.\n *\n * Usage — two pieces:\n *\n * 1. Wrap your existing middleware.ts (or use ours standalone):\n *\n *    import { withApptvty } from 'apptvty/nextjs';\n *    export default withApptvty({ apiKey: 'ak_...', siteId: 'site_...' });\n *    // or wrap your existing middleware:\n *    export default withApptvty(config, yourMiddleware);\n *\n * 2. Create app/query/route.ts for the AEO query endpoint:\n *\n *    import { createNextjsQueryHandler } from 'apptvty/nextjs';\n *    export const GET = createNextjsQueryHandler({ apiKey: 'ak_...', siteId: 'site_...' });\n *\n * The SDK logs all requests (especially agentic traffic) to Apptvty\n * and serves structured AI answers + optional sponsored ads on /query.\n */\n\nimport type { NextRequest } from 'next/server';\nimport { NextResponse } from 'next/server';\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\n/** Convert Next request headers to a plain object (Web API Headers.entries() at runtime). */\nfunction headersToRecord(h: NextRequest['headers']): Record<string, string> {\n  const entries = (h as unknown as { entries(): IterableIterator<[string, string]> }).entries();\n  return Object.fromEntries(Array.from(entries));\n}\n\n// ─── Shared singleton instances per config (keyed by apiKey) ─────────────────\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// ─── Middleware wrapper ───────────────────────────────────────────────────────\n\ntype NextMiddleware = (request: NextRequest) => Response | NextResponse | Promise<Response | NextResponse>;\n\n/**\n * Wraps a Next.js middleware function (or creates a passthrough) with\n * Apptvty request logging. All requests passing through middleware are\n * logged to Apptvty, with AI crawlers automatically classified.\n *\n * @example\n * // middleware.ts\n * import { withApptvty } from 'apptvty/nextjs';\n * export default withApptvty({ apiKey: 'ak_...', siteId: 'site_...' });\n */\nexport function withApptvty(\n  config: ApptvtyConfig,\n  next?: NextMiddleware,\n): NextMiddleware {\n  const { client, logger } = getInstance(config);\n  const queryPath = config.queryPath ?? '/query';\n\n  return async function apptvtyMiddleware(request: NextRequest): Promise<NextResponse> {\n    const startMs = Date.now();\n    const userAgent = request.headers.get('user-agent') ?? '';\n    const crawlerInfo = detectCrawler(userAgent);\n    const aiCrawlerParam = parseBoolParam(request.nextUrl.searchParams.get('ai_crawler'), false);\n    const isCrawler = crawlerInfo.isAi || aiCrawlerParam;\n\n    // Run the user's middleware (or passthrough)\n    let response: Response | NextResponse;\n    try {\n      response = next ? await next(request) : NextResponse.next();\n    } catch (err) {\n      // Don't swallow application errors\n      throw err;\n    }\n\n    const responseTimeMs = Date.now() - startMs;\n\n    // Skip logging for Next.js internals and static assets\n    const { pathname } = request.nextUrl;\n    if (shouldSkip(pathname)) {\n      return response as NextResponse;\n    }\n\n    const headers = headersToRecord(request.headers);\n    const entry: RequestLogEntry = {\n      site_id: config.siteId,\n      timestamp: new Date().toISOString(),\n      method: request.method,\n      path: pathname,\n      status_code: response.status,\n      response_time_ms: responseTimeMs,\n      ip_address: getClientIp(headers),\n      user_agent: userAgent,\n      referer: request.headers.get('referer'),\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    // Ad injection: when crawler hits an HTML page, inject sponsored ads\n    if (isCrawler && response.ok && !pathname.startsWith(queryPath)) {\n      const contentType = response.headers.get('content-type') ?? '';\n      if (contentType.includes('text/html')) {\n        try {\n          const modified = await injectAdsIntoHtml(response, client, config.siteId, pathname);\n          if (modified) return modified;\n        } catch (err) {\n          // Never break the response for ad injection failures\n          if (config.debug) console.warn('[apptvty] Ad injection failed:', err);\n        }\n      }\n    }\n\n    return response as NextResponse;\n  };\n}\n\n// ─── Query route handler ──────────────────────────────────────────────────────\n\n/**\n * Creates a Next.js App Router GET handler for the AEO query endpoint.\n *\n * @example\n * // app/query/route.ts\n * import { createNextjsQueryHandler } from 'apptvty/nextjs';\n * export const GET = createNextjsQueryHandler({ apiKey: 'ak_...', siteId: 'site_...' });\n */\nexport function createNextjsQueryHandler(config: ApptvtyConfig) {\n  const { client } = getInstance(config);\n  const handleQuery = createQueryHandler(client, config);\n\n  return async function GET(request: NextRequest): Promise<NextResponse> {\n    const { searchParams } = request.nextUrl;\n    const q = searchParams.get('q');\n    const lang = searchParams.get('lang');\n    const surfaceAds = parseBoolParam(searchParams.get('surface_ads'), true);\n    const aiCrawler = parseBoolParam(searchParams.get('ai_crawler'), false);\n    const userAgent = request.headers.get('user-agent') ?? '';\n    const headers = headersToRecord(request.headers);\n\n    const result = await handleQuery({\n      query: q,\n      lang,\n      surface_ads: surfaceAds,\n      ai_crawler: aiCrawler,\n      userAgent,\n      ipAddress: getClientIp(headers),\n      requestUrl: request.url,\n    });\n\n    return NextResponse.json(result.body, {\n      status: result.status,\n      headers: result.headers,\n    });\n  };\n}\n\n// ─── HTML ad injection ────────────────────────────────────────────────────────\n\nconst AD_INJECTION_MARKER = '<!-- apptvty-sponsored -->';\n\nfunction buildAdBlock(ads: Array<{ text: string; url: string; advertiser: string }>): string {\n  const items = ads\n    .map(\n      (ad) =>\n        `<li><a href=\"${escapeHtml(ad.url)}\" rel=\"nofollow\">${escapeHtml(ad.text)}</a> <small>— ${escapeHtml(ad.advertiser)}</small></li>`\n    )\n    .join('\\n');\n  return `\n<section aria-label=\"Sponsored\" data-sponsored ${AD_INJECTION_MARKER}>\n  <h3>Sponsored</h3>\n  <ul>${items}</ul>\n</section>`;\n}\n\nfunction escapeHtml(s: string): string {\n  return s\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&#39;');\n}\n\nasync function injectAdsIntoHtml(\n  response: Response,\n  client: ApptvtyClient,\n  siteId: string,\n  pathname: string\n): Promise<NextResponse | null> {\n  const html = await response.text();\n  if (!html || html.includes(AD_INJECTION_MARKER)) return null;\n\n  const pageAds = await client.getAdsForPage({ site_id: siteId, page_path: pathname });\n  if (!pageAds.ads || pageAds.ads.length === 0) return null;\n\n  const adBlock = buildAdBlock(pageAds.ads);\n  let modified: string;\n\n  if (html.includes('</body>')) {\n    modified = html.replace('</body>', `${adBlock}\\n</body>`);\n  } else if (html.includes('</html>')) {\n    modified = html.replace('</html>', `${adBlock}\\n</html>`);\n  } else {\n    modified = html + adBlock;\n  }\n\n  return new NextResponse(modified, {\n    status: response.status,\n    statusText: response.statusText,\n    headers: new Headers(response.headers),\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(pathname: string): boolean {\n  return (\n    pathname.startsWith('/_next/') ||\n    pathname.startsWith('/api/_') ||\n    pathname === '/favicon.ico' ||\n    /\\.(svg|png|jpg|jpeg|gif|webp|ico|woff2?|ttf|css|js\\.map)$/.test(pathname)\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/cli.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+"use strict";
+
+// src/cli.ts
+var import_readline = require("readline");
+var import_fs = require("fs");
+var import_path = require("path");
+
+// src/setup.ts
+var DEFAULT_API_URL = (typeof process !== "undefined" ? process.env?.APPTVTY_API_URL : void 0) ?? "https://api.apptvty.com";
+var RegistrationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "RegistrationError";
+  }
+};
+async function register(options) {
+  const apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+  const response = await fetch(`${apiUrl}/v1/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      domain: options.domain,
+      framework: options.framework ?? "other",
+      agent_id: options.agentId
+    }),
+    signal: AbortSignal.timeout(2e4)
+  });
+  const json = await response.json();
+  if (!response.ok) {
+    throw new RegistrationError(
+      json.error?.code ?? "REGISTRATION_FAILED",
+      json.error?.message ?? `Registration failed with status ${response.status}`
+    );
+  }
+  const data = json.data ?? json;
+  return {
+    siteId: data.site_id,
+    apiKey: data.api_key,
+    companyId: data.company_id,
+    walletAddress: data.wallet_address ?? null,
+    dashboardUrl: data.dashboard_url,
+    claimTokenExpiresAt: data.claim_token_expires_at,
+    trialEndsAt: data.trial_ends_at,
+    setup: {
+      envVars: data.setup?.env_vars ?? {
+        APPTVTY_SITE_ID: data.site_id,
+        APPTVTY_API_KEY: data.api_key
+      },
+      files: data.setup?.files
+    }
+  };
+}
+var MigrateError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MigrateError";
+  }
+};
+async function migrate(options) {
+  const apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+  const response = await fetch(`${apiUrl}/v1/sites/${options.siteId}/reindex`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${options.apiKey}`,
+      "Content-Type": "application/json"
+    },
+    signal: AbortSignal.timeout(2e4)
+  });
+  const json = await response.json();
+  const data = json.data ?? json;
+  const err = json.error;
+  if (!response.ok) {
+    throw new MigrateError(err?.code ?? "MIGRATE_FAILED", err?.message ?? `Migrate failed with status ${response.status}`);
+  }
+  return {
+    message: data.message ?? "Reindex started.",
+    siteId: data.siteId ?? options.siteId,
+    domain: data.domain ?? ""
+  };
+}
+
+// src/cli.ts
+var args = process.argv.slice(2);
+var rawCmd = args[0];
+var isMigrate = rawCmd === "migrate";
+var cmdArgs = isMigrate ? args.slice(1) : args;
+function getFlag(name, from = cmdArgs) {
+  const idx = from.indexOf(`--${name}`);
+  return idx !== -1 ? from[idx + 1] : void 0;
+}
+var isNonInteractive = cmdArgs.includes("--non-interactive") || cmdArgs.includes("--json");
+var flagDomain = getFlag("domain");
+var flagFramework = getFlag("framework");
+var flagApiUrl = getFlag("api-url");
+function detectFramework() {
+  try {
+    const pkg = JSON.parse((0, import_fs.readFileSync)((0, import_path.join)(process.cwd(), "package.json"), "utf-8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) return "nextjs";
+    if (deps.express) return "express";
+  } catch {
+  }
+  return "other";
+}
+function detectDomain() {
+  try {
+    const pkg = JSON.parse((0, import_fs.readFileSync)((0, import_path.join)(process.cwd(), "package.json"), "utf-8"));
+    if (pkg.homepage) {
+      try {
+        return new URL(pkg.homepage).hostname;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return void 0;
+}
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = (0, import_readline.createInterface)({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+function writeFile(relativePath, content, overwrite = false) {
+  const fullPath = (0, import_path.join)(process.cwd(), relativePath);
+  if ((0, import_fs.existsSync)(fullPath) && !overwrite) return false;
+  (0, import_fs.mkdirSync)((0, import_path.dirname)(fullPath), { recursive: true });
+  (0, import_fs.writeFileSync)(fullPath, content, "utf-8");
+  return true;
+}
+function appendEnvFile(path, vars) {
+  const fullPath = (0, import_path.join)(process.cwd(), path);
+  const lines = Object.entries(vars).map(([k, v]) => `${k}=${v}`).join("\n");
+  let existing = "";
+  try {
+    existing = (0, import_fs.readFileSync)(fullPath, "utf-8");
+  } catch {
+  }
+  const toAdd = Object.entries(vars).filter(([k]) => !existing.includes(k)).map(([k, v]) => `${k}=${v}`).join("\n");
+  if (!toAdd) return;
+  (0, import_fs.writeFileSync)(fullPath, existing ? `${existing}
+${toAdd}
+` : `${toAdd}
+`, "utf-8");
+}
+function loadEnvVars() {
+  const envFiles = [".env.local", ".env"];
+  let content = "";
+  for (const f of envFiles) {
+    try {
+      content = (0, import_fs.readFileSync)((0, import_path.join)(process.cwd(), f), "utf-8");
+      break;
+    } catch {
+    }
+  }
+  const out = {};
+  for (const line of content.split("\n")) {
+    const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.+?)\s*$/);
+    if (m) out[m[1]] = m[2].replace(/^["']|["']$/g, "").trim();
+  }
+  return { siteId: out.APPTVTY_SITE_ID, apiKey: out.APPTVTY_API_KEY };
+}
+async function runInit() {
+  const framework = flagFramework ?? detectFramework();
+  const detectedDomain = detectDomain();
+  if (!isNonInteractive) {
+    console.log("\n  apptvty \u2014 AI traffic analytics\n");
+    console.log(`  Framework detected: ${framework}`);
+    if (detectedDomain) console.log(`  Domain detected:    ${detectedDomain}
+`);
+  }
+  let domain = flagDomain ?? detectedDomain ?? "";
+  if (!domain && !isNonInteractive) {
+    domain = await prompt("  Enter your site domain (e.g. mysite.com): ");
+  }
+  if (!domain) {
+    if (isNonInteractive) {
+      process.stdout.write(JSON.stringify({ error: "domain is required (use --domain)" }) + "\n");
+    } else {
+      console.error("\n  \u2717 Domain is required.\n");
+    }
+    process.exit(1);
+  }
+  if (!isNonInteractive) {
+    process.stdout.write("\n  Registering with Apptvty...");
+  }
+  let result;
+  try {
+    result = await register({
+      domain,
+      framework,
+      agentId: "apptvty-cli",
+      apiUrl: flagApiUrl
+    });
+  } catch (err) {
+    const msg = err instanceof RegistrationError ? err.message : String(err);
+    if (isNonInteractive) {
+      process.stdout.write(JSON.stringify({ error: msg }) + "\n");
+    } else {
+      console.error(`
+
+  \u2717 ${msg}
+`);
+    }
+    process.exit(1);
+  }
+  if (!isNonInteractive) {
+    console.log(" done\n");
+  }
+  const envFile = framework === "nextjs" ? ".env.local" : ".env";
+  appendEnvFile(envFile, result.setup.envVars);
+  const scaffolded = [];
+  if (result.setup.files && !isNonInteractive) {
+    for (const [path, content] of Object.entries(result.setup.files)) {
+      if (path === envFile) continue;
+      const written = writeFile(path, content);
+      if (written) scaffolded.push(path);
+    }
+  }
+  if (isNonInteractive) {
+    process.stdout.write(
+      JSON.stringify({
+        site_id: result.siteId,
+        api_key: result.apiKey,
+        company_id: result.companyId,
+        wallet_address: result.walletAddress,
+        dashboard_url: result.dashboardUrl,
+        trial_ends_at: result.trialEndsAt,
+        env_file: envFile,
+        env_vars: result.setup.envVars
+      }) + "\n"
+    );
+    return;
+  }
+  console.log(`  \u2713 Site registered:     ${domain}`);
+  if (result.walletAddress) {
+    console.log(`  \u2713 Wallet created:      ${result.walletAddress}`);
+  }
+  console.log(`  \u2713 Credentials written: ${envFile}`);
+  if (scaffolded.length > 0) {
+    for (const f of scaffolded) {
+      console.log(`  \u2713 Created:             ${f}`);
+    }
+  } else if (framework === "nextjs") {
+    console.log("\n  Add these files to complete setup:");
+    console.log("\n  middleware.ts");
+    console.log("    import { withApptvty } from 'apptvty/nextjs';");
+    console.log("    export default withApptvty({ apiKey: process.env.APPTVTY_API_KEY!, siteId: process.env.APPTVTY_SITE_ID! });");
+    console.log("    export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };");
+    console.log("\n  app/query/route.ts");
+    console.log("    import { createNextjsQueryHandler } from 'apptvty/nextjs';");
+    console.log("    export const GET = createNextjsQueryHandler({ apiKey: process.env.APPTVTY_API_KEY!, siteId: process.env.APPTVTY_SITE_ID! });");
+  }
+  console.log("\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("  Free trial active \u2014 24 hours from now.");
+  console.log(`  Trial expires: ${result.trialEndsAt}`);
+  console.log("");
+  console.log("  Open the dashboard to log in before the trial ends:");
+  console.log(`  ${result.dashboardUrl}`);
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("  After the trial expires, this site's API key will stop working.");
+  console.log("  Log in once to keep your credentials and continue receiving analytics.\n");
+}
+async function runMigrate() {
+  const { siteId, apiKey } = loadEnvVars();
+  if (!siteId || !apiKey) {
+    const msg = "APPTVTY_SITE_ID and APPTVTY_API_KEY are required. Run `npx apptvty init` first, or set them in .env.local / .env.";
+    if (isNonInteractive) {
+      process.stdout.write(JSON.stringify({ error: msg }) + "\n");
+    } else {
+      console.error("\n  \u2717 " + msg + "\n");
+    }
+    process.exit(1);
+  }
+  if (!isNonInteractive) {
+    console.log("\n  apptvty \u2014 triggering reindex\n");
+    process.stdout.write("  Requesting re-crawl...");
+  }
+  try {
+    const result = await migrate({ siteId, apiKey, apiUrl: flagApiUrl });
+    if (isNonInteractive) {
+      process.stdout.write(
+        JSON.stringify({ message: result.message, site_id: result.siteId, domain: result.domain }) + "\n"
+      );
+    } else {
+      console.log(" done\n");
+      console.log(`  \u2713 ${result.message}`);
+      console.log(`  \u2713 Site: ${result.domain || result.siteId}`);
+      console.log("\n  Content will be updated within a few minutes.\n");
+    }
+  } catch (err) {
+    const msg = err instanceof MigrateError ? err.message : String(err);
+    if (isNonInteractive) {
+      process.stdout.write(JSON.stringify({ error: msg }) + "\n");
+    } else {
+      console.error(`
+
+  \u2717 ${msg}
+`);
+    }
+    process.exit(1);
+  }
+}
+async function main() {
+  if (isMigrate) {
+    await runMigrate();
+  } else {
+    await runInit();
+  }
+}
+main().catch((err) => {
+  console.error("  Unexpected error:", err);
+  process.exit(1);
+});

package/dist/index.d.mts

@@ -0,0 +1,170 @@
+import { A as ApptvtyConfig, R as RequestLogEntry, Q as QueryRequest, B as BackendQueryResponse, P as PageAdsResponse, I as ImpressionLog, S as SiteOverviewStats, D as DailyStat, C as CrawlerBreakdown, a as RecentActivityItem, b as RecentQueryItem, c as SiteWalletInfo, d as CrawlerInfo, e as AgentQueryResponse, f as QueryEndpointDiscovery, g as AgentErrorResponse } from './types-C1oUTCsT.mjs';
+export { h as PageAd, i as QuerySource, j as SponsoredAd } from './types-C1oUTCsT.mjs';
+export { createNextjsQueryHandler, withApptvty } from './middleware/nextjs.mjs';
+export { createExpressMiddleware, createExpressQueryHandler } from './middleware/express.mjs';
+import 'next/server';
+import 'node:http';
+
+/**
+ * HTTP client for the Apptvty API.
+ *
+ * Handles:
+ *   - Batch log ingestion (/v1/logs/batch)
+ *   - Query processing (/v1/query) — returns answer + optional ad
+ *   - Impression logging (/v1/impressions) — triggers billing for ads
+ */
+
+declare class ApptvtyClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly siteId;
+    private readonly debug;
+    constructor(config: ApptvtyConfig);
+    /**
+     * Send a batch of request log entries to the Apptvty ingestion API.
+     * Called by the logger's auto-flush — not called directly by user code.
+     */
+    sendLogs(logs: RequestLogEntry[]): Promise<void>;
+    /**
+     * Send a query to the Apptvty backend.
+     * The backend runs RAG against the site's indexed content and,
+     * if ads are enabled for the site, attaches a relevant sponsored ad.
+     *
+     * @throws on non-retryable errors (network errors, 5xx) — callers should catch
+     */
+    query(req: QueryRequest): Promise<BackendQueryResponse>;
+    /**
+     * Get relevant ads for a page (for HTML injection when crawler is detected).
+     * Used by middleware to inject ads into HTML responses.
+     */
+    getAdsForPage(req: {
+        site_id: string;
+        page_path: string;
+    }): Promise<PageAdsResponse>;
+    /**
+     * Log an ad impression back to Apptvty.
+     *
+     * Called after returning a query response that contains a `sponsored` block.
+     * This is what triggers the billing cycle:
+     *   - Advertiser gets charged (debited from their USDC ad budget)
+     *   - Publisher (the website) gets credited in USDC
+     *
+     * This call is fire-and-forget. The SDK logs a warning on failure
+     * but does not throw — a missed impression log is better than
+     * breaking the query response.
+     */
+    logImpression(impression: ImpressionLog): Promise<void>;
+    /** Get 30-day traffic overview (requests, AI %, crawlers, queries). */
+    getSiteStats(): Promise<SiteOverviewStats>;
+    /** Get day-by-day stats (default 30 days, max 90). */
+    getSiteDailyStats(days?: number): Promise<{
+        days: number;
+        stats: DailyStat[];
+    }>;
+    /** Get crawler breakdown by type (default 30 days). */
+    getSiteCrawlers(days?: number): Promise<{
+        days: number;
+        crawlers: CrawlerBreakdown[];
+    }>;
+    /** Get recent activity feed (last hour, default 50 items, max 200). */
+    getSiteActivity(limit?: number): Promise<{
+        activity: RecentActivityItem[];
+    }>;
+    /** Get recent agent queries (default 50, max 200). */
+    getSiteQueries(limit?: number): Promise<{
+        queries: RecentQueryItem[];
+    }>;
+    /** Get wallet balance and earnings. */
+    getSiteWallet(): Promise<SiteWalletInfo>;
+    private get;
+    private post;
+    private log;
+    private warn;
+}
+declare class ApptvtyApiError extends Error {
+    readonly statusCode: number;
+    readonly path: string;
+    readonly body: string;
+    constructor(statusCode: number, path: string, body: string);
+}
+
+/**
+ * Batched request logger.
+ *
+ * Queues RequestLogEntry objects in memory and flushes them in batches
+ * to the Apptvty API. This keeps per-request overhead near zero.
+ *
+ * Flush triggers:
+ *   1. Queue reaches batchSize (default 50)
+ *   2. flushInterval elapses (default 5s)
+ *   3. process.exit / SIGTERM (best-effort sync flush)
+ */
+
+declare class RequestLogger {
+    private readonly client;
+    private queue;
+    private timer;
+    private flushing;
+    private readonly batchSize;
+    private readonly debug;
+    constructor(client: ApptvtyClient, config: ApptvtyConfig);
+    /** Enqueue a single log entry. Non-blocking. */
+    enqueue(entry: RequestLogEntry): void;
+    /** Flush the current queue to the API. */
+    flush(): Promise<void>;
+    /**
+     * Synchronous-ish flush for process shutdown.
+     * Fires the fetch and doesn't await to avoid blocking exit handlers.
+     */
+    private flushSync;
+    /** Stop the interval timer. Call when you want to fully tear down the SDK. */
+    destroy(): void;
+    private log;
+}
+
+/**
+ * Lightweight AI crawler detection.
+ *
+ * This is the single source of truth for crawler classification in the SDK.
+ * The backend (Python analytics API and TypeScript handlers) should eventually
+ * consume this same list rather than maintaining separate copies.
+ */
+
+declare function detectCrawler(userAgent: string): CrawlerInfo;
+/** Returns the list of all known crawlers for reference (e.g. for agents.txt generation) */
+declare function getKnownCrawlerNames(): string[];
+
+/**
+ * Framework-agnostic query endpoint handler.
+ *
+ * Serves the site's AEO (Agent Experience Optimization) query page.
+ *
+ * GET /query              → Returns a self-describing discovery JSON
+ * GET /query?q=<question> → Returns an AI-generated answer from the site's
+ *                           indexed content, plus a sponsored ad if ads are
+ *                           enabled and a matching ad exists.
+ *
+ * When an ad is included in the response, this handler fires an async
+ * impression log back to Apptvty to trigger billing:
+ *   - Advertiser is charged (debited from their USDC ad budget)
+ *   - Publisher earns USDC (credited to their Crossmint wallet)
+ */
+
+interface QueryHandlerRequest {
+    query: string | null;
+    lang: string | null;
+    surface_ads?: boolean;
+    ai_crawler?: boolean;
+    userAgent: string;
+    ipAddress: string;
+    /** Full URL of the request, used to build the example in the discovery response */
+    requestUrl: string;
+}
+interface QueryHandlerResponse {
+    status: number;
+    body: AgentQueryResponse | QueryEndpointDiscovery | AgentErrorResponse;
+    headers: Record<string, string>;
+}
+declare function createQueryHandler(client: ApptvtyClient, config: ApptvtyConfig): (req: QueryHandlerRequest) => Promise<QueryHandlerResponse>;
+
+export { AgentErrorResponse, AgentQueryResponse, ApptvtyApiError, ApptvtyClient, ApptvtyConfig, CrawlerBreakdown, CrawlerInfo, DailyStat, ImpressionLog, PageAdsResponse, QueryEndpointDiscovery, RecentActivityItem, RecentQueryItem, RequestLogEntry, RequestLogger, SiteOverviewStats, SiteWalletInfo, createQueryHandler, detectCrawler, getKnownCrawlerNames };