// Types for inbox-hotspots-read.js — hand-written, same reason as speed-push.d.ts: this is OUR
// module and its projection is what an agent reads, so a caller that mistakes `measurable: false`
// for a zero reports 「nobody asked」 about a window nothing could be measured in.

/** The FALLBACK ceiling and the input `max` — the live one is `retention_days` in each answer (#998). */
export const INBOX_HOTSPOT_MAX_DAYS: 30;

/** Every failure an agent may be told about, by code. The text never comes from the response. */
export const INBOX_HOTSPOT_REFUSALS: Readonly<Record<'not_configured' | 'unauthorized' | 'unreadable', string>>;

export interface InboxHotspotRefusal extends Error {
  code: 'not_configured' | 'unauthorized' | 'unreadable';
}

export function inboxHotspotRefusal(code: string): InboxHotspotRefusal;

export interface InboxHotspotReadOptions {
  base?: string;
  secret?: string;
  days?: number;
  fetchFn?: typeof fetch;
}

/** Feelreef's raw answer. Deliberately `unknown`-ish: only `projectInboxHotspots` may read it. */
export function readInboxHotspots(
  site: { key: string },
  opts?: InboxHotspotReadOptions,
): Promise<unknown>;

/** One page's row: a path and three numbers, and nothing a visitor typed. */
export interface InboxHotspotRow {
  page: string;
  /** 🔴 Distinct sessions that ASKED here — never visits. There is no per-page visit figure. */
  asked: number;
  handed_off: number;
  handoff_rate: number;
}

export interface InboxHotspotsProjection {
  site: string;
  window_days: number;
  /** The retention the STORE reported on this call — the ceiling `window_days` was clamped to. */
  retention_days: number;
  /** 🔴 `false` is 「could not be measured」, never zero. */
  measurable: boolean;
  sessions_scanned: number;
  sessions_asked: number;
  pages_walked: number;
  truncated: boolean;
  pages: InboxHotspotRow[];
  other: { pages: number; asked: number; handed_off: number };
  coverage_note?: string;
  truncation_note?: string;
}

export function projectInboxHotspots(input: { site: string; payload: unknown }): InboxHotspotsProjection;