claude_wrapper/
types.rs

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

claude_wrapper/
types.rs
