@apideck/agent-analytics 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-import { T as TrackVisitOptions, C as CaptureEvent, A as AnalyticsAdapter } from './types-DKqlfVz6.js';
+import { T as TrackVisitOptions, C as CaptureEvent, A as AnalyticsAdapter } from './types-sQoQK-ox.js';
+export { B as BotVerificationLike } 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 +132,46 @@ 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.
- *
- * 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.
+ * Hash `input` under `secret`, returning `anon_` followed by 16 hex characters
+ * (64 bits — collision-free well past any realistic distinct-visitor count).
+ *
+ * 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;
 
-/**
- * Published crawler IP ranges, vendor by vendor.
- *
- * GENERATED FILE — do not edit by hand. Regenerate with:
- *
- *     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.
- *
- * 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.
- */
-/** 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;
+/** 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);
 }
-interface V6Range {
-    net: bigint;
-    bits: number;
-}
-interface CompiledRanges {
-    v4: V4Range[];
-    v6: V6Range[];
-}
-/**
- * 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.
- */
-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;
 
 /**
  * Escape hatch for wiring a callback directly as an analytics adapter.
@@ -248,4 +185,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 AgentClassification, type AgentKind, AnalyticsAdapter, CaptureEvent, CaptureTransportError, HTTP_CLIENT_PATTERN, HashSecretError, type HeadlessDetection, TrackVisitOptions, classifyAgent, classifyRequest, customAnalytics, detectHeadless, firstUserAgentProduct, hashId, isAiBot, isHttpClient, parseBotName, randomSecret, trackVisit };