kagi-sdk 1.0.0

Rust-first Kagi SDK with explicit official-api and session-web surfaces
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
122
123
124
125
126
127
128
129
130
131
132
133

use crate::{
    auth::{BotToken, CredentialKind, Credentials, SessionToken},
    config::ClientConfig,
    error::KagiError,
    official_api::OfficialApi,
    routing::ProtocolSurface,
    session_web::SessionWeb,
    transport::Transport,
};

#[derive(Debug, Clone)]
pub struct KagiClient {
    transport: Transport,
    credentials: Credentials,
}

impl KagiClient {
    pub fn builder() -> KagiClientBuilder {
        KagiClientBuilder::default()
    }

    pub fn new(credentials: Credentials, config: ClientConfig) -> Result<Self, KagiError> {
        let transport = Transport::new(config)?;
        Ok(Self {
            transport,
            credentials,
        })
    }

    pub fn with_bot_token(token: BotToken) -> Result<Self, KagiError> {
        Self::new(Credentials::from(token), ClientConfig::default())
    }

    pub fn with_session_token(token: SessionToken) -> Result<Self, KagiError> {
        Self::new(Credentials::from(token), ClientConfig::default())
    }

    pub fn official_api(&self) -> Result<OfficialApi<'_>, KagiError> {
        self.ensure_surface_access(ProtocolSurface::OfficialApi)?;
        Ok(OfficialApi::new(self))
    }

    pub fn session_web(&self) -> Result<SessionWeb<'_>, KagiError> {
        self.ensure_surface_access(ProtocolSurface::SessionWeb)?;
        Ok(SessionWeb::new(self))
    }

    pub(crate) fn transport(&self) -> &Transport {
        &self.transport
    }

    pub(crate) fn credentials(&self) -> &Credentials {
        &self.credentials
    }

    fn ensure_surface_access(&self, surface: ProtocolSurface) -> Result<(), KagiError> {
        let provided = self.credentials.kind();
        let expected = match surface {
            ProtocolSurface::OfficialApi => CredentialKind::BotToken,
            ProtocolSurface::SessionWeb => CredentialKind::SessionToken,
        };

        if provided != expected {
            return Err(KagiError::UnsupportedAuthSurface {
                surface,
                credential: provided,
                expected,
            });
        }

        Ok(())
    }
}

#[derive(Debug, Clone, Default)]
pub struct KagiClientBuilder {
    config: ClientConfig,
    credentials: Option<Credentials>,
    credential_conflict: Option<(CredentialKind, CredentialKind)>,
}

impl KagiClientBuilder {
    pub fn config(mut self, config: ClientConfig) -> Self {
        self.config = config;
        self
    }

    pub fn bot_token(mut self, token: BotToken) -> Self {
        self.set_credentials(Credentials::from(token));
        self
    }

    pub fn session_token(mut self, token: SessionToken) -> Self {
        self.set_credentials(Credentials::from(token));
        self
    }

    pub fn credentials(mut self, credentials: Credentials) -> Self {
        self.set_credentials(credentials);
        self
    }

    pub fn build(self) -> Result<KagiClient, KagiError> {
        if let Some((already_set, attempted)) = self.credential_conflict {
            return Err(KagiError::ConflictingCredentialConfiguration {
                already_set,
                attempted,
            });
        }

        let credentials =
            self.credentials
                .ok_or_else(|| KagiError::MissingCredentialConfiguration {
                    reason: "set bot_token(...) or session_token(...) before build()".to_string(),
                })?;

        KagiClient::new(credentials, self.config)
    }

    fn set_credentials(&mut self, next_credentials: Credentials) {
        let attempted = next_credentials.kind();

        if let Some(current_credentials) = &self.credentials {
            let already_set = current_credentials.kind();
            if already_set != attempted {
                self.credential_conflict = Some((already_set, attempted));
                return;
            }
        }

        self.credentials = Some(next_credentials);
    }
}