Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

15.4 KB
Raw Blame
#![deny(missing_docs)]

//! Typed, authenticated Rust client for the Macro Connect API.

pub mod wire;

use std::{fmt, time::Duration};

use macro_tower_layers::inject_trace_headers;
use reqwest::{Method, StatusCode, header::HeaderMap};
use tracing::Span;
use url::Url;
use zeroize::{Zeroize as _, Zeroizing};

use wire::{
    CatalogEntry, ConnectSessionRequest, ConnectSessionResponse, Connection, ConnectionsPage,
    ConnectionsQuery, ConnectionsSummary, DeleteResponse, ErrorResponse, ListedConnection,
    ListedUser, TokenResponse, UsersPage, UsersQuery,
};

/// A failure a Connect customer can act on.
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// The user has no connection to the requested app.
    #[error("app is not connected")]
    NotConnected,
    /// The user must reconnect the app.
    #[error("connection needs reauthorization")]
    NeedsReauth,
    /// The customer key was rejected.
    #[error("customer key was rejected")]
    Unauthorized,
    /// Connect could not be reached or is temporarily unavailable.
    #[error("Connect is unavailable")]
    Unavailable,
    /// Connect returned another API error.
    #[error("Connect API returned {status}: {message}")]
    Api {
        /// HTTP status code.
        status: StatusCode,
        /// API error code or response message.
        message: String,
    },
    /// Request construction or decoding failed.
    #[error("Connect client failed: {0}")]
    Internal(rootcause::Report),
}

/// Authenticated client for one Connect customer.
pub struct ConnectClient {
    base_url: Url,
    customer_key: Zeroizing<String>,
    http: reqwest::Client,
}

impl fmt::Debug for ConnectClient {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ConnectClient")
            .field("base_url", &self.base_url)
            .field("customer_key", &"[REDACTED]")
            .finish_non_exhaustive()
    }
}

/// Address and customer credential for an MCP client to dial Connect's gateway.
pub struct McpUpstream {
    /// Customer-scoped MCP gateway URL.
    pub url: Url,
    /// Customer bearer token to send to the gateway.
    pub bearer_token: String,
}

impl fmt::Debug for McpUpstream {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("McpUpstream")
            .field("url", &self.url)
            .field("bearer_token", &"[REDACTED]")
            .finish()
    }
}

impl Drop for McpUpstream {
    fn drop(&mut self) {
        self.bearer_token.zeroize();
    }
}

impl ConnectClient {
    /// Construct a client for a Connect origin or prefixed base URL.
    pub fn new(base_url: &str, customer_key: impl Into<String>) -> Result<Self, Error> {
        let base_url = Url::parse(base_url)
            .map_err(|error| Error::Internal(rootcause::Report::new(error).into_dynamic()))?;
        if !matches!(base_url.scheme(), "http" | "https")
            || base_url.cannot_be_a_base()
            || !base_url.username().is_empty()
            || base_url.password().is_some()
            || base_url.query().is_some()
            || base_url.fragment().is_some()
        {
            return Err(Error::Internal(
                rootcause::Report::new(std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "invalid Connect base URL",
                ))
                .into_dynamic(),
            ));
        }
        let http = reqwest::Client::builder()
            .connect_timeout(Duration::from_secs(10))
            .timeout(Duration::from_secs(30))
            .build()
            .map_err(|error| Error::Internal(rootcause::Report::new(error).into_dynamic()))?;
        Ok(Self {
            base_url,
            customer_key: Zeroizing::new(customer_key.into()),
            http,
        })
    }

    /// List apps available to connect.
    #[tracing::instrument(
        name = "connect.client.catalog",
        skip_all,
        fields(app_id, outcome),
        err
    )]
    pub async fn catalog(&self) -> Result<Vec<CatalogEntry>, Error> {
        self.request(Method::GET, &["v1", "catalog"], None).await
    }

    /// Fetch an official SVG icon from Connect's public catalog.
    pub async fn catalog_icon(&self, app_id: &str) -> Result<Vec<u8>, Error> {
        let mut headers = HeaderMap::new();
        inject_trace_headers(&mut headers);
        let response = self
            .http
            .get(self.route(&["v1", "catalog", app_id, "icon.svg"]))
            .headers(headers)
            .send()
            .await
            .map_err(|_| Error::Unavailable)?;
        if !response.status().is_success() {
            return Err(Error::Api {
                status: response.status(),
                message: "catalog icon unavailable".to_owned(),
            });
        }
        response
            .bytes()
            .await
            .map(|bytes| bytes.to_vec())
            .map_err(|_| Error::Unavailable)
    }

    /// Create a browser session for connecting a user's app.
    #[tracing::instrument(name = "connect.client.create_connect_session", skip_all, fields(app_id = %app_id, outcome), err)]
    pub async fn create_connect_session(
        &self,
        external_user_id: &str,
        app_id: &str,
        redirect_url: &str,
    ) -> Result<ConnectSessionResponse, Error> {
        let body = ConnectSessionRequest {
            external_user_id: external_user_id.to_owned(),
            app_id: app_id.to_owned(),
            redirect_url: redirect_url.to_owned(),
        };
        self.request(Method::POST, &["v1", "connect-sessions"], Some(&body))
            .await
    }

    /// List a user's app connections.
    #[tracing::instrument(
        name = "connect.client.connections",
        skip_all,
        fields(app_id, outcome),
        err
    )]
    pub async fn connections(&self, external_user_id: &str) -> Result<Vec<Connection>, Error> {
        self.request(
            Method::GET,
            &["v1", "users", external_user_id, "connections"],
            None,
        )
        .await
    }

    /// List one page of this customer's connections, newest first.
    #[tracing::instrument(
        name = "connect.client.list_connections",
        skip_all,
        fields(count, outcome),
        err
    )]
    pub async fn list_connections(
        &self,
        query: ConnectionsQuery,
    ) -> Result<ConnectionsPage, Error> {
        let mut url = self.route(&["v1", "connections"]);
        {
            let mut pairs = url.query_pairs_mut();
            if let Some(limit) = query.limit {
                pairs.append_pair("limit", &limit.to_string());
            }
            if let Some(cursor) = &query.cursor {
                pairs.append_pair("cursor", cursor);
            }
            if let Some(app_id) = &query.app_id {
                pairs.append_pair("app_id", app_id);
            }
            if let Some(status) = query.status {
                pairs.append_pair("status", &status.to_string());
            }
        }
        let page: ConnectionsPage = self.request_at(Method::GET, url, None).await?;
        Span::current().record("count", page.items.len());
        Ok(page)
    }

    /// Return summary counts for this customer.
    #[tracing::instrument(
        name = "connect.client.connections_summary",
        skip_all,
        fields(users, connections, outcome),
        err
    )]
    pub async fn connections_summary(&self) -> Result<ConnectionsSummary, Error> {
        let summary: ConnectionsSummary = self
            .request(Method::GET, &["v1", "connections", "summary"], None)
            .await?;
        Span::current().record("users", summary.users);
        Span::current().record("connections", summary.connections);
        Ok(summary)
    }

    /// Collect every page matching the filters. Callers should use pages for large datasets.
    pub async fn all_connections(
        &self,
        mut query: ConnectionsQuery,
    ) -> Result<Vec<ListedConnection>, Error> {
        let mut items = Vec::new();
        loop {
            let page = self.list_connections(query.clone()).await?;
            items.extend(page.items);
            match page.next_cursor {
                Some(cursor) if query.cursor.as_deref() != Some(&cursor) => {
                    query.cursor = Some(cursor)
                }
                Some(_) => {
                    return Err(Error::Internal(
                        rootcause::Report::new(std::io::Error::new(
                            std::io::ErrorKind::InvalidData,
                            "repeated connections cursor",
                        ))
                        .into_dynamic(),
                    ));
                }
                None => return Ok(items),
            }
        }
    }

    /// List one page of connected users with all of each user's connections.
    #[tracing::instrument(
        name = "connect.client.list_users",
        skip_all,
        fields(count, outcome),
        err
    )]
    pub async fn list_users(&self, query: UsersQuery) -> Result<UsersPage, Error> {
        let mut url = self.route(&["v1", "users"]);
        {
            let mut pairs = url.query_pairs_mut();
            if let Some(limit) = query.limit {
                pairs.append_pair("limit", &limit.to_string());
            }
            if let Some(cursor) = &query.cursor {
                pairs.append_pair("cursor", cursor);
            }
            if let Some(app_id) = &query.app_id {
                pairs.append_pair("app_id", app_id);
            }
            if let Some(status) = query.status {
                pairs.append_pair("status", &status.to_string());
            }
        }
        let page: UsersPage = self.request_at(Method::GET, url, None).await?;
        Span::current().record("count", page.items.len());
        Ok(page)
    }

    /// Collect all connected users matching the filters.
    pub async fn all_users(&self, mut query: UsersQuery) -> Result<Vec<ListedUser>, Error> {
        let mut items = Vec::new();
        loop {
            let page = self.list_users(query.clone()).await?;
            items.extend(page.items);
            match page.next_cursor {
                Some(cursor) if query.cursor.as_deref() != Some(&cursor) => {
                    query.cursor = Some(cursor)
                }
                Some(_) => {
                    return Err(Error::Internal(
                        rootcause::Report::new(std::io::Error::new(
                            std::io::ErrorKind::InvalidData,
                            "repeated users cursor",
                        ))
                        .into_dynamic(),
                    ));
                }
                None => return Ok(items),
            }
        }
    }

    /// Delete a user's app connection locally. The vendor grant is not revoked.
    #[tracing::instrument(name = "connect.client.delete_connection", skip_all, fields(app_id = %app_id, outcome), err)]
    pub async fn delete_connection(
        &self,
        external_user_id: &str,
        app_id: &str,
    ) -> Result<DeleteResponse, Error> {
        self.request(
            Method::DELETE,
            &["v1", "users", external_user_id, "connections", app_id],
            None,
        )
        .await
    }

    /// Export a user's current vendor access token.
    #[tracing::instrument(name = "connect.client.access_token", skip_all, fields(app_id = %app_id, outcome), err)]
    pub async fn access_token(
        &self,
        external_user_id: &str,
        app_id: &str,
    ) -> Result<TokenResponse, Error> {
        self.request(
            Method::GET,
            &[
                "v1",
                "users",
                external_user_id,
                "connections",
                app_id,
                "token",
            ],
            None,
        )
        .await
    }

    /// Return the gateway address and credential without making a network call.
    #[tracing::instrument(name = "connect.client.mcp_upstream", skip_all, fields(app_id = %app_id, outcome = "ready"))]
    pub fn mcp_upstream(&self, external_user_id: &str, app_id: &str) -> McpUpstream {
        McpUpstream {
            url: self.route(&["v1", "users", external_user_id, "mcp", app_id]),
            bearer_token: self.customer_key.to_string(),
        }
    }

    fn route(&self, parts: &[&str]) -> Url {
        let mut url = self.base_url.clone();
        // `new` accepts only hierarchical HTTP URLs, so path segments are available.
        let mut segments = url.path_segments_mut().expect("validated HTTP base URL");
        segments.pop_if_empty();
        segments.extend(parts.iter().copied());
        drop(segments);
        url
    }

    async fn request<T: serde::de::DeserializeOwned>(
        &self,
        method: Method,
        parts: &[&str],
        body: Option<&ConnectSessionRequest>,
    ) -> Result<T, Error> {
        self.request_at(method, self.route(parts), body).await
    }

    async fn request_at<T: serde::de::DeserializeOwned>(
        &self,
        method: Method,
        url: Url,
        body: Option<&ConnectSessionRequest>,
    ) -> Result<T, Error> {
        let mut headers = HeaderMap::new();
        inject_trace_headers(&mut headers);
        let mut request = self
            .http
            .request(method, url)
            .headers(headers)
            .bearer_auth(self.customer_key.as_str());
        if let Some(body) = body {
            request = request.json(body);
        }
        let response = request.send().await.map_err(|error| {
            if error.is_connect() || error.is_timeout() {
                Span::current().record("outcome", "unavailable");
                Error::Unavailable
            } else {
                Span::current().record("outcome", "internal");
                Error::Internal(rootcause::Report::new(error).into_dynamic())
            }
        })?;
        let status = response.status();
        let bytes = response.bytes().await.map_err(|error| {
            Span::current().record("outcome", "internal");
            Error::Internal(rootcause::Report::new(error).into_dynamic())
        })?;
        if !status.is_success() {
            let message = serde_json::from_slice::<ErrorResponse>(&bytes)
                .map(|response| response.error)
                .unwrap_or_else(|_| status.canonical_reason().unwrap_or("API error").to_owned());
            let error = match (status, message.as_str()) {
                (StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN, _) => Error::Unauthorized,
                (status, _) if status.is_server_error() => Error::Unavailable,
                (StatusCode::NOT_FOUND, _) => Error::NotConnected,
                (StatusCode::CONFLICT, "needs_reauth") => Error::NeedsReauth,
                _ => Error::Api { status, message },
            };
            Span::current().record(
                "outcome",
                match error {
                    Error::NotConnected => "not_connected",
                    Error::NeedsReauth => "needs_reauth",
                    Error::Unauthorized => "unauthorized",
                    Error::Unavailable => "unavailable",
                    _ => "api_error",
                },
            );
            return Err(error);
        }
        let value = serde_json::from_slice(&bytes).map_err(|error| {
            Span::current().record("outcome", "decode_error");
            Error::Internal(rootcause::Report::new(error).into_dynamic())
        })?;
        Span::current().record("outcome", "ok");
        Ok(value)
    }
}

#[cfg(test)]
mod test;