(*---------------------------------------------------------------------------
  Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
  SPDX-License-Identifier: ISC
 ---------------------------------------------------------------------------*)

(** Error handling for the claude library. *)

type t =
  | Cli_not_found of string
  | Process_error of string
  | Connection_error of string
  | Protocol_error of string
  | Timeout of string
  | Permission_denied of { tool_name : string; message : string }
  | Hook_error of { callback_id : string; message : string }
  | Control_error of { request_id : string; message : string }

exception E of t

val pp : Format.formatter -> t -> unit
(** Pretty-print an error. *)

val to_string : t -> string
(** Convert error to string. *)

val raise : t -> 'a
(** [raise err] raises [E err]. *)

(** {1 Convenience Raisers} *)

val cli_not_found : string -> 'a

val process_error : string -> 'a
(** Raise a process error. *)

val connection_error : string -> 'a
(** Raise a connection error. *)

val protocol_error : string -> 'a
(** Raise a protocol error. *)

val timeout : string -> 'a
(** Raise a timeout error. *)

val permission_denied : tool_name:string -> message:string -> 'a
(** Raise a permission denied error. *)

val hook_error : callback_id:string -> message:string -> 'a
(** Raise a hook error. *)

val control_error : request_id:string -> message:string -> 'a
(** Raise a control error. *)

(** {1 Result Helpers} *)

val ok : msg:string -> ('a, string) result -> 'a
(** [ok ~msg result] returns the Ok value or raises Protocol_error with msg
    prefix. *)

val ok' : msg:string -> ('a, string) result -> 'a
(** [ok' ~msg result] returns the Ok value or raises Protocol_error with string
    error. *)