npm - @osqd/bothandlerjs - Versions diffs - 0.3.0 → 0.5.0 - Mend

@osqd/bothandlerjs 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/CHANGELOG.md +157 -1
package/README.md +1 -1
package/dist/challenge/index.d.ts +18 -0
package/dist/challenge/interaction.d.ts +215 -0
package/dist/challenge/page.d.ts +18 -0
package/dist/cli.cjs +829 -71
package/dist/cli.cjs.map +1 -1
package/dist/cli.js +829 -71
package/dist/cli.js.map +1 -1
package/dist/config.d.ts +10 -0
package/dist/core.d.ts +15 -0
package/dist/corpus/index.cjs +20 -0
package/dist/corpus/index.cjs.map +1 -1
package/dist/corpus/index.js +20 -0
package/dist/corpus/index.js.map +1 -1
package/dist/dashboard/client/actions.d.ts +17 -0
package/dist/dashboard/client/actor.d.ts +5 -0
package/dist/dashboard/client/api.d.ts +15 -0
package/dist/dashboard/client/app.d.ts +37 -0
package/dist/dashboard/client/bars.d.ts +4 -0
package/dist/dashboard/client/boot.d.ts +5 -0
package/dist/dashboard/client/charts.d.ts +25 -0
package/dist/dashboard/client/css.d.ts +11 -0
package/dist/dashboard/client/dom.d.ts +55 -0
package/dist/dashboard/client/draft.d.ts +46 -0
package/dist/dashboard/client/feed.d.ts +22 -0
package/dist/dashboard/client/format.d.ts +37 -0
package/dist/dashboard/client/guard.d.ts +3 -0
package/dist/dashboard/client/index.d.ts +1 -0
package/dist/dashboard/client/outcome.d.ts +33 -0
package/dist/dashboard/client/pager.d.ts +32 -0
package/dist/dashboard/client/panels.d.ts +40 -0
package/dist/dashboard/client/policy.d.ts +25 -0
package/dist/dashboard/client/query.d.ts +42 -0
package/dist/dashboard/client/ranges.d.ts +2 -0
package/dist/dashboard/client/registry.d.ts +4 -0
package/dist/dashboard/client/replay.d.ts +14 -0
package/dist/dashboard/client/result.d.ts +10 -0
package/dist/dashboard/client/store.d.ts +128 -0
package/dist/dashboard/client/stream.d.ts +14 -0
package/dist/dashboard/client/tester.d.ts +1 -0
package/dist/dashboard/client/types.d.ts +69 -0
package/dist/dashboard/client.generated.d.ts +1 -1
package/dist/dashboard/page.d.ts +25 -0
package/dist/dashboard/sections.d.ts +92 -0
package/dist/dashboard/types.d.ts +2 -82
package/dist/detectors/crawler-verification.d.ts +34 -1
package/dist/detectors/index.d.ts +4 -1
package/dist/detectors/known-bots.d.ts +49 -1
package/dist/element/config.d.ts +135 -0
package/dist/element/index.cjs +5150 -0
package/dist/element/index.cjs.map +1 -0
package/dist/element/index.d.ts +137 -0
package/dist/element/index.js +5131 -0
package/dist/element/index.js.map +1 -0
package/dist/index.cjs +820 -71
package/dist/index.cjs.map +1 -1
package/dist/index.d.ts +2 -0
package/dist/index.js +811 -71
package/dist/index.js.map +1 -1
package/dist/metrics.d.ts +27 -0
package/dist/policy/index.d.ts +1 -1
package/dist/policy/presets.d.ts +47 -0
package/dist/state.d.ts +1 -1
package/docs/challenge/index.md +1 -0
package/docs/challenge/interaction.md +325 -0
package/docs/course/11-the-challenge.md +36 -1
package/docs/course/13-operating-it.md +20 -2
package/docs/detection/signatures.md +36 -0
package/docs/index.md +2 -0
package/docs/operations/dashboard.md +28 -0
package/docs/operations/embedding.md +348 -0
package/docs/operations/index.md +1 -0
package/docs/policy/presets.md +53 -0
package/docs/start/choosing-a-policy.md +1 -0
package/package.json +8 -3

package/dist/dashboard/page.d.ts CHANGED Viewed

@@ -48,4 +48,29 @@ export interface DashboardPageOptions {
  * it. The HTML is a few tens of kilobytes and identical on every request; rebuilding
  * it per view would be pure waste.
  */
+/**
+ * What the page is told about itself.
+ *
+ * Built here rather than inline in the renderer so that the embeddable element can be
+ * served the identical object from `/api/bootstrap`. The page carries it stamped into its
+ * one nonced script; the element has to ask, because it is rendered into somebody else's
+ * document and there is nothing to stamp.
+ */
+export declare function bootFor(options: DashboardPageOptions): Record<string, unknown>;
 export declare function renderDashboardPage(options: DashboardPageOptions): (nonce: string) => string;
+/**
+ * The dashboard's stylesheet, on its own.
+ *
+ * Separated from the document so the same rules can be adopted into a shadow root by the
+ * embeddable element. The selectors are written `:root, :host` throughout for that
+ * reason: `:root` matches the document element on the standalone page and matches nothing
+ * inside a shadow tree, where `:host` is the element the tokens have to hang off.
+ */
+export declare const DASHBOARD_CSS: string;
+/**
+ * Everything between `<body>` and the boot script.
+ *
+ * The standalone page and the embedded element render identical markup; only what they
+ * render it *into* differs.
+ */
+export declare const DASHBOARD_MARKUP: string;

package/dist/dashboard/sections.d.ts ADDED Viewed

@@ -0,0 +1,92 @@
+/**
+ * Which parts of the dashboard exist, as plain booleans and nothing else.
+ *
+ * Its own module because it is the one dashboard type the browser half needs: the
+ * embeddable element's `hide` option is this shape, so this file ends up in the published
+ * `.d.ts` that a front-end application reads. `types.ts` imports `node:http` — it has to,
+ * it describes a request handler — and a browser project that type-checks its dependencies
+ * strictly would have been asked to install `@types/node` to configure which panels it
+ * shows. Nothing here refers to anything outside itself, so nothing follows it in.
+ */
+/**
+ * Which parts of the dashboard exist on this listener.
+ *
+ * Everything defaults to on, and turning something off removes it from the page *and*
+ * from the server: the tab is gone, the panel is gone, the endpoint behind it answers
+ * 403, and fields a switched-off section would have shown are dropped before the data
+ * leaves the process. A viewer with devtools open sees exactly what the page sees.
+ *
+ * **There is no role model in here, deliberately.** `controls` says what a viewer may
+ * *do*; this says what a viewer may *see*; and both are fixed when the listener
+ * starts, which is what makes them cheap to reason about — no per-request evaluation,
+ * no session store, no second copy of your user table quietly disagreeing with the
+ * first. Roles are yours: run a listener per role, put your own `auth.authorize`
+ * predicate in front of each, and give each the sections and controls that role should
+ * have. `npm run demo:roles` is that arrangement, working.
+ *
+ * ```ts
+ * // An analyst sees traffic, not the reasons behind it — the evidence panel names
+ * // the exact signal that fired, which is a tuning guide for whoever is scraping you.
+ * await botHandler.serveDashboard({
+ *   port: 9684,
+ *   auth: { authorize: (req) => roleOf(req) === "analyst" },
+ *   sections: { evidence: false, policy: false },
+ *   redact: { maskIp: true },
+ * });
+ * ```
+ */
+export interface DashboardSections {
+    /** The Live feed tab, and the `/api/feed` and `/api/stream` endpoints behind it. Default true. */
+    feed?: boolean;
+    /**
+     * The case for each verdict: the evidence list with its written basis, the request
+     * headers, the query parameters, the detector failures, and the buttons that turn a
+     * row into a replay line or a corpus case. Default true.
+     *
+     * The one worth thinking about before sharing a dashboard widely. This is the half
+     * of the page that says *which detector fired and why*, which is precisely what
+     * somebody building a scraper against you needs in order to know what to fix next.
+     * Switching it off leaves the feed — what happened, to whom, and what was done —
+     * and drops the evidence from the wire, not just from the screen.
+     */
+    evidence?: boolean;
+    /** The actor drill-down, the busiest-actors panel, and per-request actor history. Default true. */
+    actors?: boolean;
+    /** The Statistics tab and the counter tiles above it. Default true. */
+    statistics?: boolean;
+    /** The traffic audit panel — the window against its baseline. Default true. */
+    audit?: boolean;
+    /** The notices panel: startup warnings, audit anomalies, detector errors. Default true. */
+    notices?: boolean;
+    /**
+     * The changes panel: what was applied at runtime, when, and by whom. Default true.
+     *
+     * The same list the traffic timeline marks. It is an audit trail rather than a log —
+     * bounded and in memory, gone with the process — so treat the panel as the convenient
+     * copy and `policy-change`, `guard-change`, `range-change` and `actor-change` as the
+     * durable one.
+     */
+    changes?: boolean;
+    /**
+     * The Actors screen: the busiest actors the *registry* is holding, which is a far
+     * larger population than the feed's ring. Default true, and it follows `actors`.
+     */
+    registry?: boolean;
+    /**
+     * The request tester: paste a User-Agent, a curl command or a raw header block and
+     * see what the engine would make of it. Default true.
+     *
+     * It runs a dry-run assessment — nothing is recorded, no counter moves — so it
+     * answers "why is this client being challenged?" without waiting for that client to
+     * come back. It shows evidence, so it follows the `evidence` section too.
+     */
+    tester?: boolean;
+    /** The Policy tab: the rules, the preview, the editor, the settings export. Default true. */
+    policy?: boolean;
+    /** The range sets panel, and the allowlist controls on it. Default true. */
+    ranges?: boolean;
+    /** The guard panel inside the Policy tab. Default true; see {@link DashboardControls.editGuard}. */
+    guard?: boolean;
+    /** The `robots.txt` the policy implies. Default true. */
+    robots?: boolean;
+}

package/dist/dashboard/types.d.ts CHANGED Viewed

@@ -1,6 +1,8 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { ActionName } from "../policy/types.js";
+import type { DashboardSections } from "./sections.js";
 import type { Assessment, BotClass, Certainty, EvidenceDirection, Verdict } from "../types.js";
+export type { DashboardSections };
 /**
  * How a viewer proves they are allowed to read the dashboard.
  *
@@ -186,88 +188,6 @@ export interface DashboardControls {
      */
     reset?: boolean;
 }
-/**
- * Which parts of the dashboard exist on this listener.
- *
- * Everything defaults to on, and turning something off removes it from the page *and*
- * from the server: the tab is gone, the panel is gone, the endpoint behind it answers
- * 403, and fields a switched-off section would have shown are dropped before the data
- * leaves the process. A viewer with devtools open sees exactly what the page sees.
- *
- * **There is no role model in here, deliberately.** `controls` says what a viewer may
- * *do*; this says what a viewer may *see*; and both are fixed when the listener
- * starts, which is what makes them cheap to reason about — no per-request evaluation,
- * no session store, no second copy of your user table quietly disagreeing with the
- * first. Roles are yours: run a listener per role, put your own `auth.authorize`
- * predicate in front of each, and give each the sections and controls that role should
- * have. `npm run demo:roles` is that arrangement, working.
- *
- * ```ts
- * // An analyst sees traffic, not the reasons behind it — the evidence panel names
- * // the exact signal that fired, which is a tuning guide for whoever is scraping you.
- * await botHandler.serveDashboard({
- *   port: 9684,
- *   auth: { authorize: (req) => roleOf(req) === "analyst" },
- *   sections: { evidence: false, policy: false },
- *   redact: { maskIp: true },
- * });
- * ```
- */
-export interface DashboardSections {
-    /** The Live feed tab, and the `/api/feed` and `/api/stream` endpoints behind it. Default true. */
-    feed?: boolean;
-    /**
-     * The case for each verdict: the evidence list with its written basis, the request
-     * headers, the query parameters, the detector failures, and the buttons that turn a
-     * row into a replay line or a corpus case. Default true.
-     *
-     * The one worth thinking about before sharing a dashboard widely. This is the half
-     * of the page that says *which detector fired and why*, which is precisely what
-     * somebody building a scraper against you needs in order to know what to fix next.
-     * Switching it off leaves the feed — what happened, to whom, and what was done —
-     * and drops the evidence from the wire, not just from the screen.
-     */
-    evidence?: boolean;
-    /** The actor drill-down, the busiest-actors panel, and per-request actor history. Default true. */
-    actors?: boolean;
-    /** The Statistics tab and the counter tiles above it. Default true. */
-    statistics?: boolean;
-    /** The traffic audit panel — the window against its baseline. Default true. */
-    audit?: boolean;
-    /** The notices panel: startup warnings, audit anomalies, detector errors. Default true. */
-    notices?: boolean;
-    /**
-     * The changes panel: what was applied at runtime, when, and by whom. Default true.
-     *
-     * The same list the traffic timeline marks. It is an audit trail rather than a log —
-     * bounded and in memory, gone with the process — so treat the panel as the convenient
-     * copy and `policy-change`, `guard-change`, `range-change` and `actor-change` as the
-     * durable one.
-     */
-    changes?: boolean;
-    /**
-     * The Actors screen: the busiest actors the *registry* is holding, which is a far
-     * larger population than the feed's ring. Default true, and it follows `actors`.
-     */
-    registry?: boolean;
-    /**
-     * The request tester: paste a User-Agent, a curl command or a raw header block and
-     * see what the engine would make of it. Default true.
-     *
-     * It runs a dry-run assessment — nothing is recorded, no counter moves — so it
-     * answers "why is this client being challenged?" without waiting for that client to
-     * come back. It shows evidence, so it follows the `evidence` section too.
-     */
-    tester?: boolean;
-    /** The Policy tab: the rules, the preview, the editor, the settings export. Default true. */
-    policy?: boolean;
-    /** The range sets panel, and the allowlist controls on it. Default true. */
-    ranges?: boolean;
-    /** The guard panel inside the Policy tab. Default true; see {@link DashboardControls.editGuard}. */
-    guard?: boolean;
-    /** The `robots.txt` the policy implies. Default true. */
-    robots?: boolean;
-}
 /** How much of each request the dashboard is allowed to show. */
 export interface DashboardRedaction {
     /**

package/dist/detectors/crawler-verification.d.ts CHANGED Viewed

@@ -1,5 +1,38 @@
-import type { Detector } from "./types.js";
+import type { Detector, DetectionContext } from "./types.js";
+import type { BotSignature } from "./known-bots.js";
+/**
+ * What an operator's own check concluded about a claimed identity.
+ *
+ * Three answers, and the third is not a formality. "I could not tell" has to be
+ * expressible and has to mean *silence* — a verifier that returned false for both "this
+ * is a forgery" and "my key server timed out" would turn an outage into an accusation.
+ */
+export type VerificationOutcome = "verified" | "refuted" | "unknown";
+/**
+ * Your own answer to "is this really who it says it is".
+ *
+ * Called with the same context the built-in checks get, for one claimed signature. It
+ * may be async: the natural implementations are a lookup or a signature check.
+ */
+export type CrawlerVerifier = (ctx: DetectionContext, signature: BotSignature) => VerificationOutcome | Promise<VerificationOutcome>;
 export interface CrawlerVerificationOptions {
+    /**
+     * Verifiers of your own, by signature id — `{ googlebot: ..., gptbot: ... }`.
+     *
+     * Most of this database cannot be checked from inside a request: the operator
+     * publishes no DNS proof and no range list, and the claim is simply unfalsifiable.
+     * That is most bots, and until now it meant the library had nothing to offer an
+     * operator who *could* check — because their CDN had already verified the crawler and
+     * said so in a header, because the bot signs its requests, or because they hold the
+     * ASN data. Writing a whole detector to say so meant reimplementing the confirm and
+     * refute semantics in this file, including the part where an inconclusive answer must
+     * stay silent.
+     *
+     * A verifier here 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 this library can do on its own.
+     */
+    verifiers?: Readonly<Record<string, CrawlerVerifier>>;
     /**
      * Treat an address with no PTR record as a forged claim. Default true.
      *

package/dist/detectors/index.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import type { CrawlerVerificationOptions } from "./crawler-verification.js";
 import type { Detector } from "./types.js";
 export type { DetectionContext, Detector, DetectorResult } from "./types.js";
 export { evidence, absenceIsMeaningful } from "./types.js";
@@ -53,4 +54,6 @@ export type { BotSignature, BotCategory, Verification } from "./known-bots.js";
  * `clearanceDetector` is not here either, because it needs the challenge service —
  * the engine adds it automatically once `challenge.secrets` is configured.
  */
-export declare function defaultDetectors(): Detector[];
+export declare function defaultDetectors(options?: {
+    crawlerVerification?: CrawlerVerificationOptions;
+}): Detector[];

package/dist/detectors/known-bots.d.ts CHANGED Viewed

@@ -16,7 +16,35 @@ import { MultiPatternMatcher } from "../internal/matcher.js";
  */
 export type BotCategory = "search" | "ai" | "seo" | "social" | "monitoring" | "archive" | "feed" | "security" | "advertising" | "library" | "headless"
 /** A real browser engine embedded in a desktop application, with a person driving it. */
- | "embedded" | "other";
+ | "embedded"
+/**
+ * Price, stock and catalogue collection: comparison shopping, marketplace feeds,
+ * repricing tools.
+ *
+ * Its own category because it is the one kind of crawling a shop has a commercial
+ * opinion about rather than a technical one. It is not `seo` — nothing here is
+ * auditing your site for you — and it is not `scraper`, which is a *behavioural*
+ * verdict this library reaches on its own. This is a client that says what it is.
+ */
+ | "commerce"
+/**
+ * Accessibility auditing: contrast, landmarks, ARIA, WCAG conformance.
+ *
+ * Separated from `monitoring` because the answer is almost always different. A site
+ * owner who blocks uptime probes still wants the tool their accessibility team runs
+ * to reach the page, and frequently does not know it is arriving as a bot at all.
+ */
+ | "accessibility"
+/**
+ * Research and measurement: universities, internet-measurement projects, plagiarism
+ * and citation indexes.
+ *
+ * Distinct from `ai` on purpose. Both read the whole page and neither sends a person,
+ * but the decision differs: an operator refusing to feed a commercial model may be
+ * perfectly happy to appear in a citation index, and folding the two together forces
+ * one answer onto two questions.
+ */
+ | "academic" | "other";
 /** Every category, for anything that has to enumerate them — a rule editor, a report. */
 export declare const BOT_CATEGORIES: readonly BotCategory[];
 /**
@@ -40,6 +68,26 @@ export type Verification = {
 } | {
     kind: "ip-ranges";
     publishedAt?: string;
+}
+/**
+ * The operator publishes a proof this library cannot check by itself, and you can.
+ *
+ * A signed request under [Web Bot Auth](https://www.rfc-editor.org/rfc/rfc9421), a
+ * CDN that has already verified the crawler and says so in a header it adds, an ASN
+ * lookup against data you hold — all of them are conclusive, and none of them are
+ * something a detection library should be doing on its own: two need a network
+ * dependency and the third needs a key it has no business fetching.
+ *
+ * So the claim is marked verifiable-by-you, and stays *unverified* until you supply a
+ * verifier for it in `crawlerVerification.verifiers`. Marked and unsupplied behaves
+ * exactly like `none`: neither confirmed nor accused.
+ *
+ * `via` names the mechanism, for the operator reading this table to know what they
+ * would have to write.
+ */
+ | {
+    kind: "proof";
+    via: string;
 } | {
     kind: "none";
 };

package/dist/element/config.d.ts ADDED Viewed

@@ -0,0 +1,135 @@
+/**
+ * The element's decisions, with no document in sight.
+ *
+ * `src/element/` is excluded from the coverage report for the same reason
+ * `src/dashboard/client/` is — it needs a document and a custom-element registry, and a
+ * number collected from a runner that cannot execute it would describe the runner. That
+ * exclusion carries a second half in the client's case, and it was missing here: the pure
+ * modules inside an excluded directory still get unit tests, they are simply not counted.
+ * This is that module for the element.
+ *
+ * Everything below answers a question with an argument rather than by looking at the page:
+ * which screens survive a config, what a status code means, where the handler is mounted,
+ * whether two configs describe the same thing. It is also where the fiddly parts live —
+ * `tabs` and `hide` naming different vocabularies, a screen the server withheld — which is
+ * exactly the logic that had bugs in it and no test able to reach them.
+ */
+import type { DashboardSections } from "../dashboard/sections.js";
+export type BotDashboardTabId = "live" | "actors" | "stats" | "policy";
+export interface BotDashboardTab {
+    id: BotDashboardTabId;
+    /** Shown in the tab strip. Defaults to the built-in name. */
+    label?: string;
+}
+/** A panel of your own, rendered beside the built-in ones. */
+export interface BotDashboardPanel {
+    id: string;
+    /** Which screen it appears on. */
+    screen: BotDashboardTabId;
+    title: string;
+    /**
+     * Where its rows come from: a URL returning `{ rows: [{ label, value, note? }] }`, or a
+     * function returning the same shape.
+     *
+     * Rendered as text, always — the same rule the rest of the client follows, and for the
+     * same reason. Nothing here interprets markup, so a value that happens to contain a tag
+     * appears as that tag rather than becoming one.
+     */
+    source: string | (() => Promise<BotDashboardRows> | BotDashboardRows);
+    /** How often to refresh, ms. Omit for once on load. */
+    refreshMs?: number;
+}
+export interface BotDashboardRows {
+    rows: ReadonlyArray<{
+        label: string;
+        value: string | number;
+        note?: string;
+    }>;
+}
+export interface BotDashboardTheme {
+    /**
+     * Token overrides, by custom property name without the leading dashes:
+     * `{ accent: "#7c3aed", surface: "#fff" }`.
+     *
+     * Applied to the host, so they cascade into the shadow root the same way the built-in
+     * tokens do. Every token the stylesheet defines can be replaced; the contrast
+     * guarantees the built-in palette was measured against are yours to keep once you do.
+     */
+    tokens?: Record<string, string>;
+    /** Force a scheme instead of following the host page and the OS. */
+    scheme?: "light" | "dark";
+    /** `compact` tightens the row and panel padding. */
+    density?: "comfortable" | "compact";
+}
+export interface BotDashboardConfig {
+    /** Where the dashboard handler is mounted. Also settable as the `src` attribute. */
+    src?: string;
+    /** Which screens appear, in which order, under which labels. */
+    tabs?: readonly BotDashboardTab[];
+    /** Panels of your own. */
+    panels?: readonly BotDashboardPanel[];
+    theme?: BotDashboardTheme;
+    /**
+     * Hide parts of the page the *server* is still serving.
+     *
+     * Cosmetic, and worth being clear about: a section switched off here is removed from
+     * the screen and stays on the wire. The `sections` option on the handler is the one
+     * that stops the data leaving the process, and it is the one to use when the point is
+     * that somebody should not have it.
+     */
+    hide?: DashboardSections;
+}
+/**
+ * The section flag that decides whether each screen exists.
+ *
+ * Omitting a tab has to be expressed this way rather than by deleting the element: the
+ * client builds its tab list from the sections it was booted with and then looks each one
+ * up, so a missing element is a crash rather than a smaller strip. Saying it in the boot
+ * object means the client removes the screen itself, the way it already does for a
+ * section the server switched off.
+ */
+export declare const TAB_SECTION: Record<BotDashboardTabId, keyof DashboardSections>;
+/**
+ * Which sections the client should be booted with, and what to say about the config.
+ *
+ * Three inputs settle it, in this order: what the server offered, what `hide` removes, and
+ * what `tabs` narrows to. The warnings are returned rather than logged because the reasons
+ * a screen goes missing are the interesting part and the caller is the only one that knows
+ * whether it has already said them.
+ */
+export declare function resolveSections(fromServer: Readonly<Record<string, boolean>>, config: Pick<BotDashboardConfig, "hide" | "tabs">): {
+    sections: Record<string, boolean>;
+    warnings: string[];
+};
+/**
+ * Where the handler is mounted, from a raw `src`.
+ *
+ * A trailing slash is dropped, and so are a query string and a fragment — the element
+ * appends `/api/bootstrap` to this, so anything after the path cannot survive that
+ * concatenation and never could. Left in, `src="/_bots?token=x"` failed with "it answered
+ * text/html — is createDashboardHandler mounted at /_bots?token=x?", which sends somebody
+ * to check the one thing that was right.
+ */
+export declare function parseMount(raw: string): {
+    base: string;
+    warning?: string;
+};
+/**
+ * What a refusal from the handler actually means to whoever has to fix it.
+ *
+ * "it answered 401" is true and useless, and 401 is not an exotic case: the documented
+ * setup is a dashboard with `auth` set, embedded in an admin page, and a background fetch
+ * cannot put up the sign-in prompt that a browser would show for a navigation. So the
+ * dashboard is simply blank with a number on it, and the number does not say that the
+ * credentials the operator already has are the answer.
+ */
+export declare function explainStatus(status: number, base: string): string;
+/**
+ * What of a config actually decides the rendered screens: which tabs, and which panels
+ * where. Deliberately not the panel `source` functions — a framework rebuilds those
+ * closures on every render, and a comparison that counted them would report a change on
+ * every render regardless of whether anything meaningful differed.
+ */
+export declare function shapeOf(config: BotDashboardConfig): string;
+/** A panel cell, as text and never as markup, and never longer than a cell should be. */
+export declare function cellText(value: unknown): string;