ncheap 0.1.0

Namecheap registrar API CLI built for terminal and AI-agent operability
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

use serde::Serialize;
use serde_json::{Value, json};

use crate::api::Error;
use crate::config::Profile;

/// Build the success envelope; separated from printing so the schema —
/// the machine contract — is unit-testable.
pub fn success_envelope<T: Serialize>(
    command: &str,
    data: &T,
    profile: &Profile,
    api_calls: u32,
) -> Value {
    json!({
        "ok": true,
        "command": command,
        "data": data,
        "error": null,
        "meta": {
            "profile": profile.name,
            "sandbox": profile.sandbox,
            "api_calls": api_calls,
        },
    })
}

/// Build the failure envelope; `meta` is null because a failure may occur
/// before a profile resolves.
pub fn failure_envelope(command: &str, err: &Error) -> Value {
    json!({
        "ok": false,
        "command": command,
        "data": null,
        "error": {
            "kind": err.kind(),
            "code": err.code(),
            "message": err.to_string(),
        },
        "meta": null,
    })
}

/// Emit the success envelope (JSON mode) or invoke the human renderer.
pub fn success<T: Serialize>(
    json_mode: bool,
    command: &str,
    data: &T,
    profile: &Profile,
    api_calls: u32,
    human: impl FnOnce(),
) {
    if json_mode {
        println!("{}", success_envelope(command, data, profile, api_calls));
    } else {
        human();
    }
}

/// Emit the failure envelope on stdout (JSON mode) or a line on stderr.
/// The process exit code is handled by the caller via Error::exit_code.
pub fn failure(json_mode: bool, command: &str, err: &Error) {
    if json_mode {
        println!("{}", failure_envelope(command, err));
    } else {
        eprintln!("error: {err}");
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::Secret;

    fn profile() -> Profile {
        Profile {
            name: "test".into(),
            api_user: "u".into(),
            api_key: Secret::new("k".into()),
            username: "u".into(),
            client_ip: "192.0.2.1".into(),
            sandbox: true,
        }
    }

    #[test]
    fn success_envelope_schema() {
        let v = success_envelope("domains.list", &vec!["a", "b"], &profile(), 2);
        assert_eq!(v["ok"], true);
        assert_eq!(v["command"], "domains.list");
        assert_eq!(v["data"].as_array().unwrap().len(), 2);
        assert!(v["error"].is_null());
        assert_eq!(v["meta"]["profile"], "test");
        assert_eq!(v["meta"]["sandbox"], true);
        assert_eq!(v["meta"]["api_calls"], 2);
        let keys: Vec<&str> = v.as_object().unwrap().keys().map(String::as_str).collect();
        assert_eq!(keys, ["command", "data", "error", "meta", "ok"]);
    }

    #[test]
    fn failure_envelope_schema() {
        let err = Error::Api {
            code: "1011150".into(),
            message: "denied".into(),
        };
        let v = failure_envelope("domains.list", &err);
        assert_eq!(v["ok"], false);
        assert!(v["data"].is_null());
        assert!(v["meta"].is_null());
        assert_eq!(v["error"]["kind"], "api");
        assert_eq!(v["error"]["code"], "1011150");
        assert!(v["error"]["message"].as_str().unwrap().contains("1011150"));
    }

    #[test]
    fn failure_envelope_code_is_null_for_non_api_errors() {
        let v = failure_envelope("raw", &Error::Usage("bad".into()));
        assert_eq!(v["error"]["kind"], "usage");
        assert!(v["error"]["code"].is_null());
    }
}