export interface Issue {
  severity: 'info' | 'low' | 'medium' | 'high' | 'critical' | string;
  category: string;
  message: string;
  location?: string | null;
  evidence?: string | null;
}

export interface AnalysisResult {
  kind: 'screenshot' | 'console' | 'network' | 'page_text';
  ok: boolean;
  issues: Issue[];
  raw: any;
  skipped: boolean;
  reason: string | null;
  error: string | null;
  duration_ms: number;
}

export interface Config {
  apiKey?: string;
  baseUrl?: string;
  enabled?: boolean;
  timeoutMs?: number;
  maxRetries?: number;
  maxRetryWaitMs?: number;
  strict?: boolean;
  sink?: string;
  sinkDir?: string;
  logFormat?: 'json' | 'junit' | 'tap' | 'text';
  /** When true, suppress all SDK-level log output (stderr). Default: false. */
  quiet?: boolean;
}

export type CheckName =
  | 'accessibility' | 'security' | 'privacy' | 'performance' | 'usability'
  | 'content' | 'forms' | 'search' | 'publishing' | 'landing_page'
  | 'checkout' | 'cart' | 'pricing' | 'error_ux' | 'ai_code' | 'ai_chatbot';

export interface Tester {
  key: string; name: string; role: string; focus: string; checks: CheckName[];
}

export interface CustomTesterSpec {
  name: string;
  role: string;
  instructions: string;
  focus?: string;
  tags?: string[];
  checks?: CheckName[];
}

export interface CustomTesterObject extends CustomTesterSpec {
  __testersai_custom: true;
}

export const CheckType: { readonly [K in string]: CheckName };
export const TESTERS: ReadonlyArray<Tester>;
export const TESTERS_BY_KEY: Readonly<Record<string, Tester>>;
export function customTester(spec: CustomTesterSpec): CustomTesterObject;

/** Any accepted selection token: enum value, alias string, tester first-name,
 *  Tester object, or CustomTester. */
export type SelectionToken = CheckName | string | Tester | CustomTesterObject;

export interface AnalyzeOpts {
  context?: Record<string, unknown>;
  /** Subset the AI analysis to specific check domains. */
  checks?: SelectionToken[];
  /** Run specific named testers (built-in first-names or custom definitions). */
  testers?: SelectionToken[];
}

export class TestersAI {
  constructor(config?: Config);
  analyzeScreenshot(image: string | Buffer | Uint8Array, opts?: AnalyzeOpts): Promise<AnalysisResult>;
  analyzeConsole(logs: string | Array<{ level?: string; text?: string }>, opts?: AnalyzeOpts): Promise<AnalysisResult>;
  analyzeNetwork(harOrEntries: any, opts?: AnalyzeOpts): Promise<AnalysisResult>;
  analyzePageText(text: string, opts?: AnalyzeOpts): Promise<AnalysisResult>;
}

export class TestersAIError extends Error {}
export function buildSinks(cfg: Config, cb?: (r: AnalysisResult) => void): Array<(r: AnalysisResult) => void>;
export function dispatch(r: AnalysisResult, sinks: Array<(r: AnalysisResult) => void>): AnalysisResult;
export function failed(r: AnalysisResult): boolean;
export function fromEnv(overrides?: Partial<Config>): Config;
