import { MisinaError } from "../errors/base.mjs";
import type { MisinaContext, MisinaPlugin } from "../types.mjs";
/**
* Circuit-breaker policy. The breaker wraps a Misina instance and tracks
* recent failures; once a threshold is crossed, subsequent requests fail
* fast with a `CircuitOpenError` until a probe (`halfOpenAfter` ms later)
* is allowed through to test recovery.
*
* State machine (Polly / cockatiel shape):
*
*   closed ──[N consecutive failures within `windowMs`]──▶ open
*   open   ──[wait `halfOpenAfter` ms]────────────────────▶ half-open
*   half-open ──[probe succeeds]───────────────────────▶ closed
*   half-open ──[probe fails]──────────────────────────▶ open (reset timer)
*/
export interface CircuitBreakerOptions {
	/** Trip the breaker after this many failures inside `windowMs`. Default: 5. */
	failureThreshold?: number;
	/** Sliding window for failure counting (ms). Default: 30_000. */
	windowMs?: number;
	/** How long to stay open before allowing a probe. Default: 10_000. */
	halfOpenAfter?: number;
	/**
	* Decide whether a settled call counts as a failure. Default: any thrown
	* error, or any 5xx HTTPError.
	*/
	isFailure?: (ctx: BreakerCallResult) => boolean;
}
export interface BreakerCallResult {
	/** The error if the call rejected, undefined on success. */
	error: Error | undefined;
	/** The Misina context for this call (request/response/options). */
	ctx: MisinaContext;
}
export type BreakerState = "closed" | "open" | "half-open";
export interface BreakerHandle {
	state: () => BreakerState;
	/** Force the breaker open (e.g. external monitoring trip). */
	trip: () => void;
	/** Force back to closed (e.g. manual recovery). */
	reset: () => void;
}
export declare class CircuitOpenError extends MisinaError {
	override readonly name = "CircuitOpenError";
	/** ms until the breaker will allow a probe. */
	readonly retryAfter: number;
	constructor(retryAfter: number);
}
/**
* Plugin that fronts a Misina with a circuit breaker. Adds a `.breaker`
* handle on the returned client for inspection and manual control.
*
* ```ts
* const api = createMisina({ use: [breaker({ failureThreshold: 3 })] })
* api.breaker.state() // "closed" | "open" | "half-open"
* ```
*/
export declare function breaker(opts?: CircuitBreakerOptions): MisinaPlugin<{
	breaker: BreakerHandle;
}>;