@apideck/agent-analytics 0.15.0 → 0.17.0

package/dist/policy-ByqnGK1b.d.ts

@@ -0,0 +1,105 @@
+import { B as BotVerificationLike } from './types-Dw43eu7D.js';
+
+/**
+ * What to do with an agent request.
+ *
+ * - `'allow'`  — serve it, free. Humans, search crawlers, and the retrieval
+ *   agents you *want* reading your site.
+ * - `'meter'`  — serve it, but count it as billable. Bulk corpus collection.
+ * - `'charge'` — don't serve it until it pays (HTTP 402).
+ * - `'block'`  — refuse. Failed identity verification, mostly.
+ */
+type AgentAction = 'allow' | 'meter' | 'charge' | 'block';
+/**
+ * Why an agent fetched the page. This is the distinction the whole module
+ * exists for, and no other signal on the request carries it.
+ *
+ * - `'retrieval'` — a person asked a question and the assistant went to read
+ *   the page for them. This is *demand*: the agent is a distribution channel,
+ *   and charging for it is charging for your own marketing.
+ * - `'training'`  — bulk corpus collection for model training. You get nothing
+ *   back per fetch, which is where a price makes sense.
+ * - `'search'`    — index crawlers, traditional and AI-native. Blocking these
+ *   costs you organic traffic or citations in an assistant's answer.
+ * - `'preview'`   — link unfurlers. Someone pasted your URL into Slack, iMessage
+ *   or a tweet and the platform fetched it to render a card. No model involved,
+ *   but blocking it means your links look broken wherever they get shared.
+ * - `'tooling'`   — coding agents and HTTP clients. Usually developers using
+ *   your docs; treat like retrieval unless you see abuse.
+ * - `'unknown'`   — everything else, including real browsers.
+ */
+type AgentIntent = 'retrieval' | 'training' | 'search' | 'preview' | 'tooling' | 'unknown';
+interface AgentDecision {
+    action: AgentAction;
+    intent: AgentIntent;
+    /** Vendor label, same string `parseBotName` returns. */
+    label: string;
+    /** Identity verdict, when a verifier was supplied. */
+    verification?: string;
+    /** Short human-readable justification — log it, don't parse it. */
+    reason: string;
+}
+interface AgentPolicyOptions {
+    /**
+     * Identity verifier. Import `verifyRequest` from
+     * `@apideck/agent-analytics/verify` and pass it here to have a `spoofed`
+     * verdict produce `'block'`.
+     *
+     * Injected rather than imported so the published IP range tables only reach
+     * bundles that use them. Only meaningful when your edge controls
+     * `x-forwarded-for`: behind a proxy that forwards a client-supplied header,
+     * an attacker picks their own verdict.
+     */
+    verify?: (req: Request) => BotVerificationLike;
+    /**
+     * A verification already computed elsewhere. Use this when your verifier is
+     * async — {@link verifyWebBotAuth} fetches a key directory, so the natural
+     * verifier from `@apideck/agent-analytics/verify` returns a promise and
+     * cannot be passed to `verify` on this synchronous function.
+     *
+     * {@link paymentGate} does this for you: it awaits the verifier and forwards
+     * the result here.
+     */
+    verification?: BotVerificationLike;
+    /** What to do with bulk training crawlers. Defaults to `'meter'`. */
+    onTraining?: AgentAction;
+    /** What to do with retrieval agents. Defaults to `'allow'` — see AgentIntent. */
+    onRetrieval?: AgentAction;
+    /** What to do with search indexers. Defaults to `'allow'`. */
+    onSearch?: AgentAction;
+    /**
+     * What to do with link unfurlers. Defaults to `'allow'` — gating these does
+     * not earn you anything, it just makes your links render as bare URLs.
+     */
+    onPreview?: AgentAction;
+    /** What to do with coding agents and HTTP clients. Defaults to `'allow'`. */
+    onTooling?: AgentAction;
+    /** Vendor labels or UA substrings always allowed, whatever the intent. */
+    allowList?: readonly string[];
+}
+/**
+ * Classify why an agent is here, from its user agent alone.
+ *
+ * This must return exactly what {@link agentPolicy} reports for the same UA.
+ * It previously did not: the `tooling` promotion for HTTP-library UAs lived
+ * only inside `agentPolicy`, so `agentIntent('curl/8.4.0')` said `'unknown'`
+ * while the policy said `'tooling'` — two exported functions disagreeing on
+ * every HTTP client, with no way for a caller to know which was right. The
+ * invariant is pinned by a test.
+ */
+declare function agentIntent(userAgent: string | null | undefined): AgentIntent;
+/**
+ * Decide what to do with a request. Pure classification plus policy — no
+ * payment rails, no network calls, nothing to configure beyond the four
+ * intent knobs.
+ *
+ * @example
+ * ```ts
+ * const decision = agentPolicy(req, { verify: true, onTraining: 'charge' })
+ * if (decision.action === 'block') return new Response(null, { status: 403 })
+ * if (decision.action === 'charge') return paymentRequired(decision)
+ * ```
+ */
+declare function agentPolicy(req: Request, opts?: AgentPolicyOptions): AgentDecision;
+
+export { type AgentIntent as A, type AgentAction as a, type AgentDecision as b, type AgentPolicyOptions as c, agentIntent as d, agentPolicy as e };

package/dist/policy-CEJ-j-Lz.d.cts

@@ -0,0 +1,105 @@
+import { B as BotVerificationLike } from './types-Dw43eu7D.cjs';
+
+/**
+ * What to do with an agent request.
+ *
+ * - `'allow'`  — serve it, free. Humans, search crawlers, and the retrieval
+ *   agents you *want* reading your site.
+ * - `'meter'`  — serve it, but count it as billable. Bulk corpus collection.
+ * - `'charge'` — don't serve it until it pays (HTTP 402).
+ * - `'block'`  — refuse. Failed identity verification, mostly.
+ */
+type AgentAction = 'allow' | 'meter' | 'charge' | 'block';
+/**
+ * Why an agent fetched the page. This is the distinction the whole module
+ * exists for, and no other signal on the request carries it.
+ *
+ * - `'retrieval'` — a person asked a question and the assistant went to read
+ *   the page for them. This is *demand*: the agent is a distribution channel,
+ *   and charging for it is charging for your own marketing.
+ * - `'training'`  — bulk corpus collection for model training. You get nothing
+ *   back per fetch, which is where a price makes sense.
+ * - `'search'`    — index crawlers, traditional and AI-native. Blocking these
+ *   costs you organic traffic or citations in an assistant's answer.
+ * - `'preview'`   — link unfurlers. Someone pasted your URL into Slack, iMessage
+ *   or a tweet and the platform fetched it to render a card. No model involved,
+ *   but blocking it means your links look broken wherever they get shared.
+ * - `'tooling'`   — coding agents and HTTP clients. Usually developers using
+ *   your docs; treat like retrieval unless you see abuse.
+ * - `'unknown'`   — everything else, including real browsers.
+ */
+type AgentIntent = 'retrieval' | 'training' | 'search' | 'preview' | 'tooling' | 'unknown';
+interface AgentDecision {
+    action: AgentAction;
+    intent: AgentIntent;
+    /** Vendor label, same string `parseBotName` returns. */
+    label: string;
+    /** Identity verdict, when a verifier was supplied. */
+    verification?: string;
+    /** Short human-readable justification — log it, don't parse it. */
+    reason: string;
+}
+interface AgentPolicyOptions {
+    /**
+     * Identity verifier. Import `verifyRequest` from
+     * `@apideck/agent-analytics/verify` and pass it here to have a `spoofed`
+     * verdict produce `'block'`.
+     *
+     * Injected rather than imported so the published IP range tables only reach
+     * bundles that use them. Only meaningful when your edge controls
+     * `x-forwarded-for`: behind a proxy that forwards a client-supplied header,
+     * an attacker picks their own verdict.
+     */
+    verify?: (req: Request) => BotVerificationLike;
+    /**
+     * A verification already computed elsewhere. Use this when your verifier is
+     * async — {@link verifyWebBotAuth} fetches a key directory, so the natural
+     * verifier from `@apideck/agent-analytics/verify` returns a promise and
+     * cannot be passed to `verify` on this synchronous function.
+     *
+     * {@link paymentGate} does this for you: it awaits the verifier and forwards
+     * the result here.
+     */
+    verification?: BotVerificationLike;
+    /** What to do with bulk training crawlers. Defaults to `'meter'`. */
+    onTraining?: AgentAction;
+    /** What to do with retrieval agents. Defaults to `'allow'` — see AgentIntent. */
+    onRetrieval?: AgentAction;
+    /** What to do with search indexers. Defaults to `'allow'`. */
+    onSearch?: AgentAction;
+    /**
+     * What to do with link unfurlers. Defaults to `'allow'` — gating these does
+     * not earn you anything, it just makes your links render as bare URLs.
+     */
+    onPreview?: AgentAction;
+    /** What to do with coding agents and HTTP clients. Defaults to `'allow'`. */
+    onTooling?: AgentAction;
+    /** Vendor labels or UA substrings always allowed, whatever the intent. */
+    allowList?: readonly string[];
+}
+/**
+ * Classify why an agent is here, from its user agent alone.
+ *
+ * This must return exactly what {@link agentPolicy} reports for the same UA.
+ * It previously did not: the `tooling` promotion for HTTP-library UAs lived
+ * only inside `agentPolicy`, so `agentIntent('curl/8.4.0')` said `'unknown'`
+ * while the policy said `'tooling'` — two exported functions disagreeing on
+ * every HTTP client, with no way for a caller to know which was right. The
+ * invariant is pinned by a test.
+ */
+declare function agentIntent(userAgent: string | null | undefined): AgentIntent;
+/**
+ * Decide what to do with a request. Pure classification plus policy — no
+ * payment rails, no network calls, nothing to configure beyond the four
+ * intent knobs.
+ *
+ * @example
+ * ```ts
+ * const decision = agentPolicy(req, { verify: true, onTraining: 'charge' })
+ * if (decision.action === 'block') return new Response(null, { status: 403 })
+ * if (decision.action === 'charge') return paymentRequired(decision)
+ * ```
+ */
+declare function agentPolicy(req: Request, opts?: AgentPolicyOptions): AgentDecision;
+
+export { type AgentIntent as A, type AgentAction as a, type AgentDecision as b, type AgentPolicyOptions as c, agentIntent as d, agentPolicy as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apideck/agent-analytics",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Track AI agent and bot traffic to your Next.js / Vercel app — PostHog, webhooks, or any custom analytics backend. Detects Claude, ChatGPT, Perplexity, Google-Extended, and more.",
   "keywords": [
     "ai",
@@ -43,6 +43,16 @@
       "import": "./dist/verify.js",
       "require": "./dist/verify.cjs"
     },
+    "./payments": {
+      "types": "./dist/pay.d.ts",
+      "import": "./dist/pay.js",
+      "require": "./dist/pay.cjs"
+    },
+    "./firewall": {
+      "types": "./dist/firewall.d.ts",
+      "import": "./dist/firewall.js",
+      "require": "./dist/firewall.cjs"
+    },
     "./posthog": {
       "types": "./dist/adapters/posthog.d.ts",
       "import": "./dist/adapters/posthog.js",
@@ -70,7 +80,8 @@
     "test:integration": "vitest run test/integration.test.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "size": "node scripts/check-size.mjs"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",