// Types for retry.js — written rather than `@ts-expect-error`'d, on the same criterion as
// build-phases.d.ts: this is OUR module and getting it wrong is customer-facing. `httpError` exists
// because a status buried in a message string is invisible to `isTransient`, which classified a
// provisioner 502 as terminal and told a customer mid-`create_site` not to retry a fault that would
// have healed. A declaration that types `status` as part of the error is the whole point — under
// `any` this import would compile just as happily while handing back a plain Error again.

/** An Error carrying the HTTP status as a FIELD, which is the only form isTransient can classify. */
export interface HttpError extends Error {
  status: number;
  /** An explicit verdict from the failing service, when it knows better than its status code does. */
  retryable?: boolean;
}

/** Build the error to throw when an HTTP call fails, so retry classification actually works. */
export function httpError(status: number, message: string, opts?: { retryable?: boolean }): HttpError;

/** Transient (worth retrying) vs terminal. An explicit `retryable` wins; else 429 and 5xx are
 *  transient, as are transport failures. A misconfigured service answers 500 and says `false`. */
export function isTransient(err: unknown): boolean;

/** `isTransient`, except a `TimeoutError` (whole-request deadline) is not retried — the explicit
 *  opt-out for callers not yet shown safe to retry a request that may still be running (#1551). */
export function isTransientUnlessTimedOut(err: unknown): boolean;

export interface RetryOptions {
  attempts?: number;
  baseDelayMs?: number;
  maxDelayMs?: number;
  onRetry?: (info: { attempt: number; delay: number; err: unknown }) => void;
  sleep?: (ms: number) => Promise<void>;
  isTransient?: (err: unknown) => boolean;
}

/** Run `fn`, retrying only transient failures. Rethrows with `.retryable` and `.attempts` set. */
export function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;