refactor: move payments and the firewall recommender behind subpaths

The root bundle had grown from 9,643 to 22,497 bytes — undoing most of the 65%
reduction in #21 — because payments, gateway, entitlement and firewall all
exported from the package root. Every consumer paid for them whether or not they
charged anyone, and the firewall recommender in particular is an offline
analysis tool that will never execute in middleware.

  dist/index.js     22,497 -> 11,608 B   (8,695 -> 4,546 gzipped)
  dist/pay.js                 10,861 B   opt-in
  dist/firewall.js             6,821 B   opt-in

Entry points now:

  @apideck/agent-analytics            detection, classification, agentPolicy, trackVisit
  @apideck/agent-analytics/verify     Web Bot Auth + published IP range tables
  @apideck/agent-analytics/payments   402 challenges, gateways, entitlements
  @apideck/agent-analytics/firewall   WAF recommendations (offline)
  @apideck/agent-analytics/markdown   Markdown-twin negotiation

agentPolicy stays in the root: classification without a policy to apply it to is
half a library, and it costs ~2 kB. That is why the root lands at 11.6 kB rather
than back at 9.6 kB.

README gains an entry-point table with the real numbers, and every import
example in the README, the testing guide and the site now points at the right
subpath. Verified from a clean install of the packed package that all five entry
points resolve.

Found while pulling accurate figures for the site's install section, which was
still advertising "216 tests" and "CI on Node 18, 20 and 22" — Node 18 was
dropped in 0.12 for lacking globalThis.crypto, so the site was claiming support
for a runtime the library refuses to run on. Both corrected.

Author: Gdewilde

README.md

@@ -104,7 +104,7 @@ extra steps.
 So start by counting:
 
 ```ts
-import { paymentGate } from '@apideck/agent-analytics'
+import { paymentGate } from '@apideck/agent-analytics/payments'
 import { combinedVerifier } from '@apideck/agent-analytics/verify'
 
 const gate = await paymentGate(req, {
@@ -125,7 +125,7 @@ When you know the number, switch to an entitlement: one 402 advertising a bulk
 offer, one settlement, a reusable credential.
 
 ```ts
-import { entitlementGateway } from '@apideck/agent-analytics'
+import { entitlementGateway } from '@apideck/agent-analytics/payments'
 
 const gate = await paymentGate(req, {
   onTraining: 'charge',
@@ -258,7 +258,7 @@ every rule comes out in `log` mode and Vercel stages rule changes as drafts, so
 nothing is live until you run `vercel firewall publish` yourself.
 
 ```ts
-import { recommendFirewallRules, firewallScript } from '@apideck/agent-analytics'
+import { recommendFirewallRules, firewallScript } from '@apideck/agent-analytics/firewall'
 
 const rules = recommendFirewallRules(observations) // aggregate from your warehouse
 console.log(firewallScript(rules))                // runnable, commented bash
@@ -282,6 +282,24 @@ privacy relays egress from hosting networks.
 See [`docs/TESTING-PAYMENTS.md`](./docs/TESTING-PAYMENTS.md) for testing the
 payment path end to end.
 
+## Entry points
+
+The root carries detection, classification, policy and capture — what every
+consumer needs. Everything optional lives behind a subpath, so it only reaches
+your bundle if you import it.
+
+| Import | Contains | Root bundle cost |
+| --- | --- | ---: |
+| `@apideck/agent-analytics` | detection, classification, `agentPolicy`, `trackVisit` | 11.6 kB / **4.5 kB gz** |
+| `…/verify` | Web Bot Auth + published IP range tables | 19.0 kB |
+| `…/payments` | 402 challenges, gateways, entitlements | 10.9 kB |
+| `…/firewall` | WAF rule recommendations (offline tool) | 6.8 kB |
+| `…/markdown` | Markdown-twin content negotiation | 2.0 kB |
+
+This split is load-bearing rather than tidy-minded. Exporting the payment and
+firewall surfaces from the root once pushed it from 9.6 kB to 22.5 kB — every
+site paid for a firewall recommender that will never run in middleware.
+
 ## Install
 
 ```bash

docs/TESTING-PAYMENTS.md

@@ -21,7 +21,7 @@ npm i @apideck/agent-analytics
 
 ```js
 // pay.mjs
-import { paymentGate, entitlementGateway, memoryEntitlementStore } from '@apideck/agent-analytics'
+import { paymentGate, entitlementGateway, memoryEntitlementStore } from '@apideck/agent-analytics/payments'
 import { combinedVerifier } from '@apideck/agent-analytics/verify'
 
 const store = memoryEntitlementStore({ lic_abc: { id: 'lic_abc', remaining: 3 } })
@@ -72,7 +72,7 @@ prove:** that any real agent understands the challenge.
 ### Inspect the challenge
 
 ```js
-import { paymentRequired } from '@apideck/agent-analytics'
+import { paymentRequired } from '@apideck/agent-analytics/payments'
 
 const res = paymentRequired({
   challenges: [
@@ -101,7 +101,7 @@ Wire the gate into middleware, then drive it with user agents.
 ```ts
 // middleware.ts
 import { NextResponse, type NextRequest } from 'next/server'
-import { paymentGate, entitlementGateway } from '@apideck/agent-analytics'
+import { paymentGate, entitlementGateway } from '@apideck/agent-analytics/payments'
 import { combinedVerifier } from '@apideck/agent-analytics/verify'
 
 const gateway = entitlementGateway({
@@ -206,7 +206,7 @@ Stripe's SDK generates challenges and settles; wrap it rather than
 reimplementing.
 
 ```ts
-import { mppxGateway } from '@apideck/agent-analytics'
+import { mppxGateway } from '@apideck/agent-analytics/payments'
 
 const mppx = Mppx.create({ methods: [...], secretKey })
 const handler = Mppx.compose(

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apideck/agent-analytics",
   "version": "0.15.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.",
+  "description": "Track AI agent and bot traffic to your Next.js / Vercel app \u2014 PostHog, webhooks, or any custom analytics backend. Detects Claude, ChatGPT, Perplexity, Google-Extended, and more.",
   "keywords": [
     "ai",
     "agents",
@@ -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",

src/index.ts

@@ -1,3 +1,13 @@
+/**
+ * Package root: detection, classification, policy and capture.
+ *
+ * Deliberately excludes the paid-access surface and the firewall recommender.
+ * Both are opt-in and neither belongs in an edge bundle by default:
+ *
+ *     @apideck/agent-analytics/verify     identity verification + IP ranges
+ *     @apideck/agent-analytics/payments   402 challenges, gateways, entitlements
+ *     @apideck/agent-analytics/firewall    WAF rule recommendations (offline)
+ */
 export { trackVisit } from './track.js'
 export {
   AI_BOT_PATTERN,
@@ -14,23 +24,6 @@ export type { AgentClassification, AgentKind, HeadlessDetection } from './bots.j
 export { hashId, randomSecret, HashSecretError } from './hash.js'
 export { CaptureTransportError } from './errors.js'
 export { agentIntent, agentPolicy } from './policy.js'
-export { mppxGateway, paymentGate, x402Gateway } from './gateway.js'
-export { entitlementGateway, memoryEntitlementStore } from './entitlement.js'
-export { firewallScript, recommendFirewallRules } from './firewall.js'
-export type {
-  FirewallAction,
-  FirewallCondition,
-  FirewallRecommendation,
-  RateLimitSpec,
-  RecommendOptions,
-  TrafficObservation
-} from './firewall.js'
-export type {
-  BulkOffer,
-  Entitlement,
-  EntitlementGatewayOptions,
-  EntitlementStore
-} from './entitlement.js'
 export type {
   GatewayResult,
   Meter,
@@ -40,13 +33,6 @@ export type {
   PaymentGateway,
   X402GatewayOptions
 } from './gateway.js'
-export {
-  hasPaymentPayload,
-  paymentPayload,
-  paymentRequired,
-  respondToDecision,
-  withSettlement
-} from './payments.js'
 export type {
   MppChallenge,
   PaymentChallenge,

src/pay.ts

@@ -0,0 +1,14 @@
+/**
+ * Paid-access entry point. **EXPERIMENTAL** — see `payments.ts`.
+ *
+ * Kept out of the package root deliberately. Charging is opt-in and rare;
+ * classification is what every consumer needs. Exporting these from the root
+ * put the challenge builders, the gateway and the entitlement store into every
+ * edge bundle whether or not the site ever charged anyone — the root grew from
+ * 9.6 kB to 22.5 kB before anyone noticed.
+ *
+ *     import { paymentGate } from '@apideck/agent-analytics/payments'
+ */
+export * from './payments.js'
+export * from './gateway.js'
+export * from './entitlement.js'

tsup.config.ts

@@ -5,6 +5,8 @@ export default defineConfig({
     'src/index.ts',
     'src/markdown.ts',
     'src/verify.ts',
+    'src/pay.ts',
+    'src/firewall.ts',
     'src/adapters/posthog.ts',
     'src/adapters/webhook.ts'
   ],