@osqd/bothandlerjs 0.4.0 → 0.5.0

package/dist/state.d.ts

@@ -153,7 +153,7 @@ export declare class ActorRegistry {
      * A read, and only a read: it neither records a request against an actor nor moves
      * one up the LRU, so watching the list cannot change what it lists.
      */
-    top(limit: number, now: number): ActorSummary[];
+    top(limit: number, now: number, offset?: number): ActorSummary[];
     forget(key: string): void;
     clear(): void;
     /** Marks an actor as holding valid human clearance until `until`. */

package/docs/detection/signatures.md

@@ -41,6 +41,18 @@ individual name does not.
 | `library` | curl, wget, python-requests, Go-http-client, okhttp | usually challenge |
 | `headless` | HeadlessChrome, Playwright, Puppeteer, Selenium | usually challenge |
 | `embedded` | Smart TVs, set-top boxes, game consoles | allow |
+| `commerce` | idealo, Kelkoo, PriceRunner, Trivago, Skyscanner, Indeedbot | a commercial decision |
+| `academic` | Crossref, OpenAlex, university web-science crawls | usually allow |
+| `accessibility` | Siteimprove and other WCAG auditors | allow |
+
+The last three are separate from their nearest neighbours because the decision is. A price
+comparator is not an SEO auditor — nothing there is auditing your site for you, and the
+same crawler is a distribution channel to one retailer and a competitor's research tool to
+the next, which is why nothing in `commerce` is marked benign. A citation index is not a
+model being trained, and an operator refusing the second is often glad of the first. And an
+accessibility crawler is not an uptime probe: it is usually commissioned by the site's own
+owner and then forgotten about, so blocking it does not reduce load, it makes an
+accessibility report look clean by removing the evidence.
 
 ```ts
 { id: "no-ai", match: { category: "ai" }, action: "block", reason: "Not for model training." }
@@ -54,6 +66,7 @@ What, if anything, can check the claim:
 type Verification =
   | { kind: "fcrdns"; domains: readonly string[] }   // reverse DNS, forward-confirmed
   | { kind: "ip-ranges"; publishedAt?: string }      // an address list the operator publishes
+  | { kind: "proof"; via: string }                   // something only you can check
   | { kind: "none" };                                // no published mechanism
 ```
 
@@ -62,6 +75,29 @@ them, and for those the claim is **unfalsifiable**. The library neither confirms
 accuses — it records what the client said and lets the policy decide what a self-declared
 identity is worth. See [verifying a crawler](verification.md).
 
+**But you may be able to check what this library cannot.** Your CDN has often already
+verified the crawler and says so in a header it adds; some bots now sign their requests;
+you may hold ASN data. None of those belong inside a detection library — two need a
+network dependency and the third needs a key it has no business fetching — so instead you
+supply the answer:
+
+```ts
+new BotHandler({
+  crawlerVerification: {
+    verifiers: {
+      // Whatever you can prove, however you prove it.
+      gptbot: (ctx) => (ctx.facts.headers["cf-verified-bot"] === "gptbot" ? "verified" : "unknown"),
+    },
+  },
+});
+```
+
+A verifier returns `"verified"`, `"refuted"` or `"unknown"`, runs before the built-in check
+for that signature, and a definite answer settles it — which also means no DNS lookup.
+`"unknown"` falls through to whatever the library can do on its own, and so does a throw:
+an unreachable key server must never read as an accusation, or an outage becomes a wave of
+blocked crawlers.
+
 ## What a name is worth
 
 A matched signature makes `self-identified` produce `certain` evidence, and this is the

package/docs/operations/dashboard.md

@@ -29,6 +29,12 @@ User-Agent, the verdict, the score, the action and the rule that chose it. Filte
 proven, suspected, human, guard stops, denied, mitigated or served; or type into the
 search box.
 
+The feed pages, fifty requests at a time. The newest page follows the stream; stepping
+back holds the list still while you read it — a feed that renumbers itself under somebody
+paging through it cannot be read — and says **held while you read** so the stillness is
+not mistaken for quiet. Requests keep arriving and keep being counted; they are at the
+front when you return to it.
+
 The search takes fields, and negation, because the two cases people actually reach for
 it are an address that also appears inside a User-Agent and a path that is a prefix of
 ten others:
@@ -108,6 +114,17 @@ regularity (near zero is a metronome, which no person is), prior confirmations,
 whether they hold clearance. **In feed** sends one to the live feed as an `actor:` filter,
 which makes it a shareable URL like every other view.
 
+This screen pages too, twenty-five at a time, busiest first. The registry holds far more
+clients than the feed's ring holds requests, and paging is what reaches them: the feed
+already shows you what is loudest, and the population behind it is the reason this screen
+exists. Ranking something that is still moving means a client can shift between pages
+while you read; the order is a snapshot of a live list, not a stable index.
+
+The **Actors tracked** counter above the tab strip is the way in: it is a button, so
+pressing it — or reaching it with the keyboard and pressing Enter — opens this screen.
+Where the `registry` section is switched off there is no Actors screen to open, and the
+counter stays an ordinary tile rather than offering to go somewhere that does not exist.
+
 **Statistics** — a traffic timeline (1m/5m/15m/1h) split by outcome, which says how
 much history the window actually holds rather than drawing a flat line through time it
 never had; the assessment-latency histogram with mean, p95 and max; and the **score
@@ -383,6 +400,15 @@ capped at `maxEventsPerSecond` (100 by default, `0` to remove it). What is cappe
 still see every request, and the feed says how many were not streamed. A thinned feed
 must never look like a quiet one.
 
+**And it does not stop at saying so.** Next to that count is **Load them**, which fetches
+the ring and merges what is missing back into the feed, in the order it happened. Nothing
+was ever lost — the cap and the lag guard both keep entries off the *stream* and leave the
+ring alone — so this is the same data arriving by a different road. It is a button rather
+than something automatic on purpose: entries are skipped exactly when the origin is
+busiest, and a dashboard that answered every skip by re-fetching the whole ring would be a
+load amplifier pointed at the process it is watching, which is what the cap exists to
+prevent.
+
 **A viewer that stops reading is not allowed to cost you memory.** A socket that has
 stopped draining — a laptop that slept with the tab open, a phone in a tunnel, a proxy
 that stopped reading — used to accumulate frames in this process, one queue per viewer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osqd/bothandlerjs",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },