@apideck/agent-analytics 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { T as TrackVisitOptions, C as CaptureEvent, A as AnalyticsAdapter } from './types-DKqlfVz6.js';
+import { T as TrackVisitOptions, B as BotVerificationLike, C as CaptureEvent, A as AnalyticsAdapter } from './types-sQoQK-ox.js';
 export { posthogAnalytics } from './adapters/posthog.js';
 export { webhookAnalytics } from './adapters/webhook.js';
 
 /**
- * Capture an event describing the incoming request. Fire-and-forget: awaits
- * the adapter but swallows errors so a downed analytics backend never breaks
- * the response path. Callers typically don't await the returned promise.
+ * Capture an event describing the incoming request. Fire-and-forget: awaits the
+ * adapter but routes errors to {@link TrackVisitOptions.onError} rather than
+ * letting them reach the response path. Callers typically don't await it.
  *
  * By default, captures every request so coding-agent traffic (axios, curl,
  * Electron, …) shows up alongside branded crawlers. Set `onlyBots: true` to
@@ -131,110 +131,120 @@ declare function classifyAgent(userAgent: string | null | undefined): AgentClass
 declare function classifyRequest(req: Request): AgentClassification;
 
 /**
- * djb2 hash returning an 8-char hex string prefixed with `anon_`. Used to
- * build stable anonymous distinct-ids from `ip:ua:...` tuples without
- * collecting identifying data. Not cryptographic — collisions are fine for
- * analytics segmentation.
- */
-declare function hashId(input: string): string;
-
-/**
- * Verdict on whether a request's claimed crawler identity holds up against the
- * vendor's published IP ranges.
+ * Keyed, non-reversible anonymous identifiers.
  *
- * - `'verified'` — the UA claims a vendor we can check, and the client IP is
- *   inside that vendor's published ranges. High confidence.
- * - `'spoofed'` — the UA claims a vendor we can check, and the IP is **not**
- *   in its ranges. Someone is impersonating the crawler.
- * - `'unverifiable'` — the UA claims a vendor that publishes no feed we bundle
- *   (Bytespider, Amazon, Meta, …), or no usable client IP was available.
- * - `'not-claimed'` — the UA doesn't claim a verifiable crawler at all. This is
- *   the normal verdict for browsers and HTTP clients; it is *not* a negative
- *   finding.
+ * The previous implementation was an unsalted 32-bit djb2 over `ip:userAgent`.
+ * Because the user agent is emitted in plaintext on the same event, an attacker
+ * held half the preimage and only had to search the IPv4 space — recovering a
+ * residential IP took 75 seconds single-threaded. That is pseudonymisation, not
+ * anonymisation, and it does not survive GDPR Recital 26.
+ *
+ * This uses HMAC-SHA-256 with a caller-supplied secret, truncated to 64 bits.
+ * Web Crypto is available on Vercel Edge, Cloudflare Workers, Deno and Node 18+.
  */
-type VerificationVerdict = 'verified' | 'spoofed' | 'unverifiable' | 'not-claimed';
-/** Why a request could not be judged. Only set when verdict is 'unverifiable'. */
-type UnverifiableReason = 'no-published-ranges' | 'client-side-agent' | 'no-client-ip';
-interface BotVerification {
-    verdict: VerificationVerdict;
-    reason?: UnverifiableReason;
-    /** Vendor label the UA claims, when it claims one. */
-    claimed: string | null;
-    /**
-     * Convenience boolean for filtering: `true` only for `'verified'`, `false`
-     * only for `'spoofed'`, `null` when no judgement was possible. Deliberately
-     * tri-state — collapsing "unverifiable" into `false` would brand every
-     * Bytespider and Amazonbot hit an impostor.
-     */
-    verified: boolean | null;
+/** Thrown when a secret is missing or unusable. */
+declare class HashSecretError extends Error {
+    constructor(message: string);
 }
-/** Vendor labels this build can produce a verified/spoofed verdict for. */
-declare function verifiableVendors(): readonly string[];
 /**
- * Check a claimed crawler identity against the vendor's published IP ranges.
+ * Hash `input` under `secret`, returning `anon_` followed by 16 hex characters
+ * (64 bits — collision-free well past any realistic distinct-visitor count).
  *
- * Pass the client IP you already trust — on Vercel and Cloudflare that is the
- * first hop of `x-forwarded-for`. If your edge doesn't strip client-supplied
- * `X-Forwarded-For`, an attacker controls this value and a `'verified'` verdict
- * means nothing; verify your proxy's behaviour before relying on it.
+ * The secret must be stable across instances for identifiers to be comparable
+ * over time, and secret from anyone who can read your events: publishing it
+ * makes the identifier exactly as reversible as the old implementation was.
+ * Rotating it deliberately breaks continuity, which is correct behaviour for a
+ * privacy-preserving id.
  */
-declare function verifyBotIdentity(userAgent: string | null | undefined, ip: string | null | undefined): BotVerification;
+declare function hashId(input: string, secret: string): Promise<string>;
 /**
- * Extract the client IP the way {@link trackVisit} does — first hop of
- * `x-forwarded-for`, falling back to the platform-specific headers.
+ * Generate a random secret. Used as the default when none is configured, so the
+ * privacy-preserving path is the one you get by doing nothing. Identifiers are
+ * then only stable within a single instance's lifetime — set a real secret when
+ * you need them comparable across instances and over time.
  */
-declare function clientIpFromRequest(req: Request): string;
-/** Verify straight from a request object. */
-declare function verifyRequest(req: Request): BotVerification;
+declare function randomSecret(): string;
+
+/** Thrown when the analytics backend rejects, errors, or times out a capture. */
+declare class CaptureTransportError extends Error {
+    readonly status: number | undefined;
+    readonly body: string | undefined;
+    constructor(message: string, status?: number, body?: string);
+}
 
 /**
- * Published crawler IP ranges, vendor by vendor.
- *
- * GENERATED FILE — do not edit by hand. Regenerate with:
+ * What to do with an agent request.
  *
- *     node scripts/refresh-bot-ranges.mjs
- *
- * Keys match the labels {@link parseBotName} returns, so a claimed identity
- * maps to its range list without a translation table.
- *
- * Only vendors that publish a machine-readable feed appear here. A vendor's
- * absence means "cannot be verified", never "not a real bot" — see
- * {@link verifyBotIdentity} for how that distinction is surfaced.
+ * - `'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.
  *
- * Freshness is the whole ballgame: these lists rotate. Almost every OpenAI
- * prefix is an Azure block and every Anthropic prefix is GCP or similar, so
- * "came from a datacenter" proves nothing on its own — only membership in the
- * current published list does. A stale snapshot produces false 'spoofed'
- * verdicts on legitimate crawlers, which is the failure mode to fear.
+ * - `'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'`    — classic index crawlers. Blocking these costs you SEO.
+ * - `'tooling'`   — coding agents and HTTP clients. Usually developers using
+ *   your docs; treat like retrieval unless you see abuse.
+ * - `'unknown'`   — everything else, including real browsers.
  */
-/** When these ranges were captured from the vendor feeds (UTC). */
-declare const BOT_RANGES_CAPTURED_AT = "2026-08-02T00:00:00Z";
-declare const BOT_IP_RANGES: Readonly<Record<string, readonly string[]>>;
-/** Vendor labels this build can verify. Anything else yields a null verdict. */
-declare const VERIFIABLE_VENDORS: readonly string[];
-
-interface V4Range {
-    net: number;
-    mask: number;
-}
-interface V6Range {
-    net: bigint;
-    bits: number;
+type AgentIntent = 'retrieval' | 'training' | 'search' | '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 CompiledRanges {
-    v4: V4Range[];
-    v6: V6Range[];
+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;
+    /** 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 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. */
+declare function agentIntent(userAgent: string | null | undefined): AgentIntent;
 /**
- * Pre-compile a list of CIDR strings into numeric form. Invalid entries are
- * dropped rather than thrown — a malformed line in a vendor's published feed
- * shouldn't take down the whole check.
+ * 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 compileRanges(cidrs: readonly string[]): CompiledRanges;
-/** True when `ip` falls inside any range in the pre-compiled set. */
-declare function ipInRanges(ip: string, ranges: CompiledRanges): boolean;
-/** Convenience wrapper — compiles on every call, so prefer {@link ipInRanges}. */
-declare function ipInCidr(ip: string, cidr: string): boolean;
+declare function agentPolicy(req: Request, opts?: AgentPolicyOptions): AgentDecision;
 
 /**
  * Escape hatch for wiring a callback directly as an analytics adapter.
@@ -248,4 +258,4 @@ declare function ipInCidr(ip: string, cidr: string): boolean;
  */
 declare function customAnalytics(capture: (event: CaptureEvent) => Promise<void> | void): AnalyticsAdapter;
 
-export { AI_BOT_PATTERN, type AgentClassification, type AgentKind, AnalyticsAdapter, BOT_IP_RANGES, BOT_RANGES_CAPTURED_AT, type BotVerification, CaptureEvent, type CompiledRanges, HTTP_CLIENT_PATTERN, type HeadlessDetection, TrackVisitOptions, VERIFIABLE_VENDORS, type VerificationVerdict, classifyAgent, classifyRequest, clientIpFromRequest, compileRanges, customAnalytics, detectHeadless, firstUserAgentProduct, hashId, ipInCidr, ipInRanges, isAiBot, isHttpClient, parseBotName, trackVisit, verifiableVendors, verifyBotIdentity, verifyRequest };
+export { AI_BOT_PATTERN, type AgentAction, type AgentClassification, type AgentDecision, type AgentIntent, type AgentKind, type AgentPolicyOptions, AnalyticsAdapter, BotVerificationLike, CaptureEvent, CaptureTransportError, HTTP_CLIENT_PATTERN, HashSecretError, type HeadlessDetection, TrackVisitOptions, agentIntent, agentPolicy, classifyAgent, classifyRequest, customAnalytics, detectHeadless, firstUserAgentProduct, hashId, isAiBot, isHttpClient, parseBotName, randomSecret, trackVisit };