/**
 * What is actually wrong with a configured server URL.
 *
 * THE FAILURE THIS EXISTS TO END. `doctor` used to do:
 *
 *     fetch(`${base}/api/capabilities`).then((r) => r.json())
 *
 * with no `r.ok` check, inside one try/catch. A host that had been renamed
 * away served an HTML 404 page, `.json()` choked on `<!DO`, and the user was
 * told:
 *
 *     ✗ Server reachable   unreachable: Unexpected non-whitespace character
 *                          after JSON at position 4
 *
 * Three different problems with three different fixes — a stale token, a moved
 * server, a server that is down — all arrived as that one sentence. And the
 * "Logged in" row above it printed a green tick, because it only checked that
 * credentials.json had an entry.
 *
 * So: classify, then advise. Every branch names the URL and the command that
 * fixes it.
 */
export type ProbeResult = 
/** Spoke to a chat-recall server and understood the answer. `raw` is the
 *  parsed document, so a caller needing more fields off /api/capabilities
 *  (the sync client wants `limits`) reads them from THIS probe instead of
 *  issuing a second, unclassified request — which is how the sync client
 *  ended up with its own `.json()` and its own JSON-parse offsets. */
{
    kind: 'ok';
    apiVersion: number;
    edition?: string;
    cliVersion?: string;
    raw: Record<string, unknown>;
}
/** Reached an HTTP server, but nothing is mounted here. Usually a moved host. */
 | {
    kind: 'moved';
    status: number;
}
/** The server is there and refused the credential. */
 | {
    kind: 'unauthorized';
    status: number;
}
/** The server is there and broken. */
 | {
    kind: 'server_error';
    status: number;
}
/** 2xx, but not a chat-recall API — a proxy, a captive portal, a parked domain. */
 | {
    kind: 'not_api';
    status: number;
    snippet: string;
}
/** Never got an HTTP response at all: DNS, TLS, connection, timeout. */
/** No HTTP response at all. `reason` names WHY — the thing `fetch failed`
 *  refuses to tell you — and `error` keeps the raw string for a report. */
 | {
    kind: 'unreachable';
    error: string;
    reason: UnreachableReason;
};
/** Why a request never got an answer. Node's fetch reports every one of these as
 *  the same five characters, "fetch failed", with the real code hidden in
 *  `err.cause`. A user pasting that string leaves nothing to diagnose — which is
 *  exactly what happened on a macOS install: the message named SSO, the cause
 *  was the network, and nobody could tell which. */
export type UnreachableReason = 'dns' | 'refused' | 'tls' | 'timeout' | 'reset' | 'bad_port' | 'unknown';
/** True when the probe proves a usable chat-recall server. */
export declare function probeOk(r: ProbeResult): r is Extract<ProbeResult, {
    kind: 'ok';
}>;
/**
 * Probe `<base>/api/capabilities`, which is unauthenticated and cheap.
 *
 * `fetchImpl` is injectable so the classification is testable without a server —
 * the whole point of this module is behaviour on responses that are hard to
 * produce on demand (an HTML 404, a parked domain, a 502).
 */
export declare function probeServer(base: string, opts?: {
    timeoutMs?: number;
    fetchImpl?: typeof fetch;
}): Promise<ProbeResult>;
/**
 * One line the user can act on. Never a stack trace, always the next command.
 */
export declare function probeAdvice(r: ProbeResult, base: string): string;
/**
 * Dig the real code out of a fetch failure.
 *
 * `err.message` on a failed `fetch` is the constant string "fetch failed" for
 * every network cause there is. undici puts the truth in `err.cause`, one or two
 * levels down, as a Node error code. Walk the chain and classify.
 */
export declare function classifyUnreachable(err: unknown): UnreachableReason;
/** The most specific string available: the underlying code where there is one,
 *  because "fetch failed" is worth nothing in a bug report. */
export declare function describeCause(err: unknown): string;
/**
 * One sentence naming WHY a request never got an answer — for the callers that
 * have no URL to advise about and only need to say what happened.
 *
 * `describeCause` alone degrades to "fetch failed" whenever no error in the
 * chain carries a `code`, and `init` printed exactly that: "Not connected. fetch
 * failed". The reason is the part a person can act on, so it leads.
 */
export declare function describeUnreachable(err: unknown): string;
//# sourceMappingURL=server-probe.d.ts.map