claude_wrapper/
types.rs

1//! Shared enums and serde types used across the command builders.
2//!
3//! Small value types like [`Transport`], [`Scope`], [`Effort`],
4//! [`PermissionMode`], [`OutputFormat`], and [`InputFormat`] that map
5//! onto `claude` CLI flag values, with `Display`/`FromStr` and serde
6//! wiring so they round-trip cleanly through args and JSON.
7
8use std::fmt;
9use std::str::FromStr;
10
11use serde::{Deserialize, Serialize};
12
13/// Transport type for MCP server connections.
14///
15/// # Example
16///
17/// ```
18/// use claude_wrapper::Transport;
19/// use std::str::FromStr;
20///
21/// let t = Transport::from_str("stdio").unwrap();
22/// assert_eq!(t, Transport::Stdio);
23/// assert_eq!(t.to_string(), "stdio");
24///
25/// let t: Transport = "http".parse().unwrap();
26/// assert_eq!(t, Transport::Http);
27/// ```
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
29#[serde(rename_all = "lowercase")]
30pub enum Transport {
31    /// Standard I/O transport — server runs as a subprocess.
32    Stdio,
33    /// HTTP transport — server accessible via URL.
34    Http,
35    /// Server-Sent Events transport — server accessible via URL with SSE.
36    Sse,
37}
38
39impl fmt::Display for Transport {
40    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
41        match self {
42            Self::Stdio => write!(f, "stdio"),
43            Self::Http => write!(f, "http"),
44            Self::Sse => write!(f, "sse"),
45        }
46    }
47}
48
49/// Error returned when parsing an unknown transport string.
50#[derive(Debug, Clone, thiserror::Error)]
51#[error("unknown transport: {0}")]
52pub struct TransportParseError(pub String);
53
54impl FromStr for Transport {
55    type Err = TransportParseError;
56
57    fn from_str(s: &str) -> Result<Self, Self::Err> {
58        match s {
59            "stdio" => Ok(Self::Stdio),
60            "http" => Ok(Self::Http),
61            "sse" => Ok(Self::Sse),
62            other => Err(TransportParseError(other.to_string())),
63        }
64    }
65}
66
67impl TryFrom<&str> for Transport {
68    type Error = TransportParseError;
69
70    fn try_from(s: &str) -> Result<Self, Self::Error> {
71        s.parse()
72    }
73}
74
75#[cfg(test)]
76mod transport_tests {
77    use super::*;
78
79    #[test]
80    fn from_str_accepts_known_variants() {
81        assert_eq!("stdio".parse::<Transport>().unwrap(), Transport::Stdio);
82        assert_eq!("http".parse::<Transport>().unwrap(), Transport::Http);
83        assert_eq!("sse".parse::<Transport>().unwrap(), Transport::Sse);
84    }
85
86    #[test]
87    fn from_str_returns_error_for_unknown() {
88        let err = "websocket".parse::<Transport>().unwrap_err();
89        assert!(err.to_string().contains("websocket"));
90    }
91
92    #[test]
93    fn try_from_str_returns_error_for_unknown() {
94        assert!(Transport::try_from("bogus").is_err());
95    }
96}
97
98/// Output format for `--output-format`.
99#[derive(Debug, Clone, Copy, Default)]
100pub enum OutputFormat {
101    /// Plain text output (default).
102    #[default]
103    Text,
104    /// Single JSON result object.
105    Json,
106    /// Streaming NDJSON.
107    StreamJson,
108}
109
110impl OutputFormat {
111    pub(crate) fn as_arg(&self) -> &'static str {
112        match self {
113            Self::Text => "text",
114            Self::Json => "json",
115            Self::StreamJson => "stream-json",
116        }
117    }
118}
119
120/// Permission mode for `--permission-mode`.
121#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
122#[serde(rename_all = "camelCase")]
123pub enum PermissionMode {
124    /// Default interactive permissions.
125    #[default]
126    Default,
127    /// Auto-accept file edits.
128    AcceptEdits,
129    /// Bypass all permission checks.
130    ///
131    /// **Deprecated.** Reaching for this variant directly puts a
132    /// bypass-mode query one keystroke away in any code path, which
133    /// is exactly the footgun the variant enables. Use
134    /// [`crate::dangerous::DangerousClient`] instead, which gates
135    /// construction on the `CLAUDE_WRAPPER_ALLOW_DANGEROUS` env-var
136    /// and makes the intent obvious at the call site. The variant
137    /// itself will stay available through the current major version
138    /// so existing callers keep compiling (with a deprecation
139    /// warning).
140    #[deprecated(
141        since = "0.5.1",
142        note = "use claude_wrapper::dangerous::DangerousClient instead; \
143                direct BypassPermissions usage is a footgun and will go \
144                away in a future major release"
145    )]
146    BypassPermissions,
147    /// Don't ask for permissions (deny by default).
148    DontAsk,
149    /// Plan mode (read-only).
150    Plan,
151    /// Auto mode.
152    Auto,
153}
154
155impl PermissionMode {
156    pub(crate) fn as_arg(&self) -> &'static str {
157        match self {
158            Self::Default => "default",
159            Self::AcceptEdits => "acceptEdits",
160            #[allow(deprecated)]
161            Self::BypassPermissions => "bypassPermissions",
162            Self::DontAsk => "dontAsk",
163            Self::Plan => "plan",
164            Self::Auto => "auto",
165        }
166    }
167}
168
169/// Input format for `--input-format`.
170#[derive(Debug, Clone, Copy, Default)]
171pub enum InputFormat {
172    /// Plain text input (default).
173    #[default]
174    Text,
175    /// Streaming JSON input.
176    StreamJson,
177}
178
179impl InputFormat {
180    pub(crate) fn as_arg(&self) -> &'static str {
181        match self {
182            Self::Text => "text",
183            Self::StreamJson => "stream-json",
184        }
185    }
186}
187
188/// Effort level for `--effort`.
189#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
190#[serde(rename_all = "lowercase")]
191pub enum Effort {
192    /// Low effort.
193    Low,
194    /// Medium effort (default).
195    Medium,
196    /// High effort.
197    High,
198    /// Extra-high effort.
199    Xhigh,
200    /// Maximum effort, most thorough.
201    Max,
202}
203
204impl Effort {
205    pub(crate) fn as_arg(&self) -> &'static str {
206        match self {
207            Self::Low => "low",
208            Self::Medium => "medium",
209            Self::High => "high",
210            Self::Xhigh => "xhigh",
211            Self::Max => "max",
212        }
213    }
214}
215
216/// Scope for MCP and plugin commands.
217#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
218pub enum Scope {
219    /// Local scope (current directory).
220    #[default]
221    Local,
222    /// User scope (global).
223    User,
224    /// Project scope.
225    Project,
226    /// Managed scope -- plugins installed by an outer manager
227    /// rather than directly by the user. Accepted by `claude plugin
228    /// update --scope managed` as of CLI 2.1.143.
229    Managed,
230}
231
232impl Scope {
233    pub(crate) fn as_arg(&self) -> &'static str {
234        match self {
235            Self::Local => "local",
236            Self::User => "user",
237            Self::Project => "project",
238            Self::Managed => "managed",
239        }
240    }
241}
242
243/// Authentication status returned by `claude auth status --json`.
244///
245/// # Example
246///
247/// ```no_run
248/// # async fn example() -> claude_wrapper::Result<()> {
249/// let claude = claude_wrapper::Claude::builder().build()?;
250/// let status = claude_wrapper::AuthStatusCommand::new()
251///     .execute_json(&claude).await?;
252///
253/// if status.logged_in {
254///     println!("Logged in as {}", status.email.unwrap_or_default());
255/// }
256/// # Ok(())
257/// # }
258/// ```
259#[cfg(feature = "json")]
260#[derive(Debug, Clone, Deserialize, Serialize)]
261#[serde(rename_all = "camelCase")]
262pub struct AuthStatus {
263    /// Whether the user is currently logged in.
264    #[serde(default)]
265    pub logged_in: bool,
266    /// Authentication method (e.g. "claude.ai").
267    #[serde(default)]
268    pub auth_method: Option<String>,
269    /// API provider (e.g. "firstParty").
270    #[serde(default)]
271    pub api_provider: Option<String>,
272    /// Authenticated user's email address.
273    #[serde(default)]
274    pub email: Option<String>,
275    /// Organization ID.
276    #[serde(default)]
277    pub org_id: Option<String>,
278    /// Organization name.
279    #[serde(default)]
280    pub org_name: Option<String>,
281    /// Subscription type (e.g. "pro", "max").
282    #[serde(default)]
283    pub subscription_type: Option<String>,
284    /// Any additional fields not explicitly modeled.
285    #[serde(flatten)]
286    pub extra: std::collections::HashMap<String, serde_json::Value>,
287}
288
289/// A message from a query result, representing one turn in the conversation.
290#[cfg(feature = "json")]
291#[derive(Debug, Clone, Deserialize, Serialize)]
292pub struct QueryMessage {
293    /// The role of the message sender (e.g., "user", "assistant").
294    #[serde(default)]
295    pub role: String,
296    /// The text content of the message.
297    #[serde(default)]
298    pub content: serde_json::Value,
299    /// Additional fields returned by the CLI not captured in typed fields.
300    #[serde(flatten)]
301    pub extra: std::collections::HashMap<String, serde_json::Value>,
302}
303
304/// Result from a query with `--output-format json`.
305#[cfg(feature = "json")]
306#[derive(Debug, Clone, Deserialize, Serialize)]
307pub struct QueryResult {
308    /// The text content of the query response.
309    #[serde(default)]
310    pub result: String,
311    /// The session ID for continuing conversations.
312    #[serde(default)]
313    pub session_id: String,
314    /// Total cost of the query in USD.
315    #[serde(default, rename = "total_cost_usd", alias = "cost_usd")]
316    pub cost_usd: Option<f64>,
317    /// Duration of the query in milliseconds.
318    #[serde(default)]
319    pub duration_ms: Option<u64>,
320    /// Number of conversation turns in the query.
321    #[serde(default)]
322    pub num_turns: Option<u32>,
323    /// Whether the query resulted in an error.
324    #[serde(default)]
325    pub is_error: bool,
326    /// Additional fields returned by the CLI not captured in typed fields.
327    #[serde(flatten)]
328    pub extra: std::collections::HashMap<String, serde_json::Value>,
329}
330
331#[cfg(all(test, feature = "json"))]
332mod tests {
333    use super::*;
334
335    #[test]
336    fn query_result_deserializes_total_cost_usd() {
337        let json =
338            r#"{"result":"hello","session_id":"s1","total_cost_usd":0.042,"is_error":false}"#;
339        let qr: QueryResult = serde_json::from_str(json).unwrap();
340        assert_eq!(qr.cost_usd, Some(0.042));
341    }
342
343    #[test]
344    fn query_result_deserializes_cost_usd_alias() {
345        let json = r#"{"result":"hello","session_id":"s1","cost_usd":0.01,"is_error":false}"#;
346        let qr: QueryResult = serde_json::from_str(json).unwrap();
347        assert_eq!(qr.cost_usd, Some(0.01));
348    }
349
350    #[test]
351    fn query_result_missing_cost_defaults_to_none() {
352        let json = r#"{"result":"hello","session_id":"s1","is_error":false}"#;
353        let qr: QueryResult = serde_json::from_str(json).unwrap();
354        assert_eq!(qr.cost_usd, None);
355    }
356
357    #[test]
358    fn query_result_from_stream_result_event() {
359        // Exact shape of a --output-format stream-json "result" event.
360        // The flattened `extra` must absorb type/subtype without
361        // breaking typed field parsing.
362        let json = r#"{"type":"result","subtype":"success","result":"streamed","session_id":"sess-1","total_cost_usd":0.03,"num_turns":1,"is_error":false}"#;
363        let qr: QueryResult = serde_json::from_str(json).unwrap();
364        assert_eq!(qr.cost_usd, Some(0.03));
365        assert_eq!(qr.num_turns, Some(1));
366        assert_eq!(qr.session_id, "sess-1");
367        assert_eq!(qr.result, "streamed");
368        assert_eq!(
369            qr.extra.get("type").and_then(|v| v.as_str()),
370            Some("result")
371        );
372    }
373
374    #[test]
375    fn query_result_deserializes_num_turns() {
376        let json = r#"{"result":"done","session_id":"s2","total_cost_usd":0.1,"num_turns":5,"is_error":false}"#;
377        let qr: QueryResult = serde_json::from_str(json).unwrap();
378        assert_eq!(qr.num_turns, Some(5));
379        assert_eq!(qr.cost_usd, Some(0.1));
380    }
381
382    #[test]
383    fn query_result_serializes_as_total_cost_usd() {
384        let qr = QueryResult {
385            result: "ok".into(),
386            session_id: "s1".into(),
387            cost_usd: Some(0.05),
388            duration_ms: None,
389            num_turns: Some(3),
390            is_error: false,
391            extra: Default::default(),
392        };
393        let json = serde_json::to_string(&qr).unwrap();
394        assert!(json.contains("\"total_cost_usd\""));
395        assert!(json.contains("\"num_turns\""));
396    }
397}
claude_wrapper/types.rs

claude_wrapper/
types.rs
