import { type AnalyticsReader, type AnalyticsResult, type Range, type SeriesPoint, type TopRow } from "./model.js"; export type BotTrafficLevel = "none" | "watch" | "likely"; export type BotTrafficReasonCode = "hourly_spike" | "direct_entrances" | "single_browser" | "single_page"; export interface BotTrafficReason { readonly code: BotTrafficReasonCode; /** One plain sentence (English) for agents and logs: numbers, an hour, an id or a browser family. */ readonly detail: string; /** `hourly_spike`: times the median hour; the others: a share (0–1, three decimals). */ readonly value: number; /** The threshold `value` was compared with. */ readonly threshold: number; /** `single_page`: the node id; `single_browser`: the browser family. */ readonly key?: string; } export interface BotTrafficSignal { readonly level: BotTrafficLevel; /** What raised the level; empty for `none`. */ readonly reasons: readonly BotTrafficReason[]; /** The busiest hour checked (bucket start, UTC); `null` when the hours checked had no page views. */ readonly hour: string | null; /** Page views in that hour. */ readonly pageviews: number; /** The median hour of the 7 days checked (the busiest hour left out). */ readonly baseline: number; /** The hours checked: the last 7 days of the period, never past the current hour. */ readonly window: Range | null; /** Part of the hours could not be read (live budget spent, no live reader): `none` may be wrong. */ readonly partial?: true; } export interface BotTrafficThresholds { readonly windowDays: number; readonly minPeakPageviews: number; readonly watchMultiple: number; readonly likelyMultiple: number; readonly directShare: number; readonly minEntrances: number; readonly browserShare: number; readonly pageShare: number; } /** Conservative defaults; the RFC fixes 20× and 80 %, the rest is documented in its notes. */ export declare const BOT_TRAFFIC_THRESHOLDS: BotTrafficThresholds; export declare const NO_BOT_TRAFFIC: BotTrafficSignal; /** Times the median hour (one decimal); a median below 1 counts as 1. */ export declare function spikeMultiple(pageviews: number, baseline: number): number; /** The busiest hour at or after `from` (the earliest on a tie) and the median of every other hour. */ export declare function findPeakHour(points: readonly SeriesPoint[], from: Date): { peak: SeriesPoint; baseline: number; } | null; /** What the busiest hour looked like (the top lists of that one hour). */ export interface PeakHourEvidence { readonly hour: string; readonly pageviews: number; readonly baseline: number; /** Entrances in the hour (all channels) and those without a referrer. */ readonly visits: number; readonly directVisits: number; readonly topBrowser?: TopRow | undefined; readonly topNode?: TopRow | undefined; } /** The level and its reasons from the busiest hour (pure; the thresholds are explicit). */ export declare function classifyBotTraffic(e: PeakHourEvidence, t?: BotTrafficThresholds): Pick; export interface AssessBotTrafficInput { readonly siteId: string; /** The period on screen; its last `windowDays` days are checked. */ readonly range: Range; readonly now: Date; readonly thresholds?: BotTrafficThresholds; } /** * Runs the check through any reader (a raw store, or the composite read path): the hourly series * of the window, then — only when the gate passes — the busiest hour's channels, browsers and * pages. Returns the signal and every result read (for `source`/`estimated`/`partial`). A spent * live budget gives `none` with `partial`; other errors propagate. */ export declare function assessBotTraffic(reader: AnalyticsReader, input: AssessBotTrafficInput): Promise<{ signal: BotTrafficSignal; results: AnalyticsResult[]; }>;