(** Immiche - Immich API client library

    This library provides a clean Eio-based interface to interact with Immich
    instances for managing people and face recognition data.
*)

(** {1 Types} *)

(** Type representing an Immich client with connection pooling *)
type t

(** Type representing a person in Immich *)
type person = {
  id: string;
  name: string;
  birth_date: string option;
  thumbnail_path: string;
  is_hidden: bool;
  unknown: Jsont.json;  (** Unknown/extra JSON fields preserved during parsing *)
}

(** Type for the people API response *)
type people_response = {
  total: int;
  visible: int;
  people: person list;
  unknown: Jsont.json;  (** Unknown/extra JSON fields preserved during parsing *)
}

(** {1 Client Creation} *)

(** [create ~requests_session ~base_url ~api_key] creates a new Immich client.

    @param requests_session Shared Requests session for connection pooling
    @param base_url The base URL of the Immich instance (e.g., "https://photos.example.com")
    @param api_key The API key for authentication
    @return An Immich client configured for the specified instance
*)
val create :
  requests_session:Requests.t ->
  base_url:string ->
  api_key:string ->
  t

(** {1 API Functions} *)

(** [fetch_people client] fetches all people from an Immich instance.

    @param client The Immich client
    @return A people_response containing all people and metadata
    @raise Failure if the API request fails
*)
val fetch_people : t -> people_response

(** [fetch_person client ~person_id] fetches details for a single person.

    @param client The Immich client
    @param person_id The ID of the person to fetch
    @return The person details
    @raise Failure if the API request fails or person not found
*)
val fetch_person : t -> person_id:string -> person

(** [download_thumbnail client ~fs ~person_id ~output_path] downloads
    a person's thumbnail image to a file.

    @param client The Immich client
    @param fs The Eio filesystem capability
    @param person_id The ID of the person whose thumbnail to download
    @param output_path The file path where the thumbnail should be saved
    @return Ok () on success, or Error with a message on failure
*)
val download_thumbnail :
  t ->
  fs:_ Eio.Path.t ->
  person_id:string ->
  output_path:string ->
  (unit, [> `Msg of string]) result

(** [search_person client ~name] searches for people by name.

    @param client The Immich client
    @param name The name to search for
    @return A list of matching people
    @raise Failure if the API request fails
*)
val search_person : t -> name:string -> person list