This repository has no description
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** JMAP CLI configuration and cmdliner terms
7
8 This module provides reusable cmdliner terms for building JMAP CLI tools.
9 It handles configuration from command-line arguments and environment
10 variables with proper precedence.
11
12 {2 Environment Variables}
13
14 - [JMAP_SESSION_URL] - JMAP session URL
15 - [JMAP_API_KEY] - API key or Bearer token
16 - [JMAP_API_KEY_FILE] - Path to file containing API key
17 - [JMAP_ACCOUNT_ID] - Account ID (optional)
18
19 {2 Configuration Precedence}
20
21 1. Command-line flags (e.g., [--url], [--api-key])
22 2. Environment variables (e.g., [JMAP_SESSION_URL])
23 3. Default values (where applicable)
24*)
25
26(** {1 Configuration Types} *)
27
28(** Source of a configuration value. *)
29type source =
30 | Default (** Value from default *)
31 | Env of string (** Value from environment variable *)
32 | Cmdline (** Value from command line *)
33
34(** CLI configuration with source tracking. *)
35type config = {
36 session_url : string;
37 session_url_source : source;
38 api_key : string;
39 api_key_source : source;
40 account_id : string option;
41 account_id_source : source;
42 debug : bool;
43}
44
45(** {1 Pretty Printing} *)
46
47val pp_source : source Fmt.t
48(** Pretty-print a configuration source. *)
49
50val pp_config : config Fmt.t
51(** Pretty-print the configuration (with masked API key). *)
52
53(** {1 Cmdliner Terms} *)
54
55val config_term : config Cmdliner.Term.t
56(** Combined cmdliner term for JMAP configuration.
57 Includes session URL, API key (direct or from file), account ID, and debug flag. *)
58
59val session_url_term : string option Cmdliner.Term.t
60(** Cmdliner term for session URL. *)
61
62val api_key_term : string option Cmdliner.Term.t
63(** Cmdliner term for API key. *)
64
65val api_key_file_term : string option Cmdliner.Term.t
66(** Cmdliner term for API key file path. *)
67
68val account_id_term : string option Cmdliner.Term.t
69(** Cmdliner term for account ID. *)
70
71val debug_term : bool Cmdliner.Term.t
72(** Cmdliner term for debug flag. *)
73
74(** {1 Environment Documentation} *)
75
76val env_docs : string
77(** Documentation string describing environment variables for use in man pages. *)
78
79(** {1 Client Helpers} *)
80
81val create_client :
82 sw:Eio.Switch.t ->
83 Eio_unix.Stdenv.base ->
84 config ->
85 Client.t
86(** [create_client ~sw env cfg] creates a JMAP client from the configuration.
87 Exits with error message on connection failure. *)
88
89val get_account_id : config -> Client.t -> Jmap.Proto.Id.t
90(** [get_account_id cfg client] returns the account ID from config, or the
91 primary mail account if not specified. Exits with error if no account found. *)
92
93val debug : config -> ('a, Format.formatter, unit) format -> 'a
94(** [debug cfg fmt ...] prints a debug message to stderr if debug mode is enabled. *)