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.

16.5 KB
Raw Blame
pub(crate) mod attachments;
pub(crate) mod auth;
pub(crate) mod contacts;
mod error;
pub(crate) mod filters;
pub(crate) mod history;
pub(crate) mod labels;
pub(crate) mod messages;
pub(crate) mod profile;
pub(crate) mod send_as;
pub(crate) mod threads;
pub(crate) mod watch;

#[cfg(test)]
mod test;

use regex::Regex;
use std::sync::LazyLock;
use std::time::Duration;

const MAX_ERROR_BODY_LEN: usize = 1024;
// A stalled request fails instead of holding its worker, and its mailbox's
// request-gate permit, indefinitely. Callers size permit leases above this.
const REQUEST_TIMEOUT: Duration = Duration::from_secs(60);
const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);

static EMAIL_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}").unwrap());

/// Sanitize a Gmail API error body: redact email addresses, cap length.
pub(crate) fn sanitize_error_body(body: &str) -> String {
    let redacted = EMAIL_REGEX.replace_all(body, "[REDACTED_EMAIL]");
    let trimmed = redacted.trim();
    if trimmed.len() <= MAX_ERROR_BODY_LEN {
        return trimmed.to_string();
    }

    let truncate_at = trimmed
        .char_indices()
        .map(|(index, _)| index)
        .take_while(|index| *index <= MAX_ERROR_BODY_LEN)
        .last()
        .unwrap_or(0);
    format!("{}… (truncated)", &trimmed[..truncate_at])
}

use crate::auth::{fetch_google_public_keys, verify_google_jwt};
use crate::contacts::get_self_connection;
use crate::messages::{get_message, get_message_label_ids, list_messages};
use crate::threads::get_thread;
pub use error::GmailApiHttpError;
use models_email::gmail::contacts::{ConnectionsResponse, OtherContactsResponse, PersonResource};
pub use models_email::gmail::filters::Filter;
use models_email::gmail::inbox_sync::{
    GoogleJwtClaims, GooglePublicKeys, JwtVerificationError, KeyMap,
};
use models_email::gmail::labels::GmailLabel;
use models_email::gmail::{
    GmailUserProfile, HistoryListResponse, ListThreadsResponse, MessageResource, ThreadResource,
};

#[derive(Clone, Debug)]
pub struct GmailClient {
    /// The inner client used to make requests
    inner: reqwest::Client,
    /// Sending crosses a durable submission boundary and must never be retried
    /// or redirected automatically by the transport.
    send_client: reqwest::Client,
    /// The base url for Gmail API
    base_url: String,
    /// The url for fetching google certs
    certs_url: String,
    /// The url for fetching contact information via People API
    contacts_url: String,
    /// The expected audience for the jwt passed by Google
    audience: String,
    /// The GCP topic name we listen on for inbox updates
    subscription_topic: Option<String>,
}

impl GmailClient {
    /// Client for API calls that do not register push subscriptions.
    pub fn without_watch() -> Self {
        Self::new_with_urls(
            None,
            "https://www.googleapis.com/gmail/v1".to_string(),
            "https://people.googleapis.com/v1".to_string(),
            "https://www.googleapis.com/oauth2/v3/certs".to_string(),
            "macro-gmail-webhook".to_string(),
        )
    }

    pub fn new(subscription_topic: String) -> Self {
        Self::new_with_urls(
            subscription_topic,
            "https://www.googleapis.com/gmail/v1".to_string(),
            "https://people.googleapis.com/v1".to_string(),
            "https://www.googleapis.com/oauth2/v3/certs".to_string(),
            "macro-gmail-webhook".to_string(),
        )
    }

    /// Creates a client with injectable Gmail, People, and JWKS URLs.
    ///
    /// This constructor supports deterministic tests and Gmail-compatible
    /// endpoints. HTTP transport details and endpoint values remain private to
    /// this crate.
    pub fn new_with_urls(
        subscription_topic: impl Into<Option<String>>,
        gmail_url: String,
        people_url: String,
        jwks_url: String,
        audience: String,
    ) -> Self {
        Self {
            inner: reqwest::Client::builder()
                .timeout(REQUEST_TIMEOUT)
                .connect_timeout(CONNECT_TIMEOUT)
                .build()
                .expect("Gmail HTTP client should initialize"),
            send_client: reqwest::Client::builder()
                .timeout(REQUEST_TIMEOUT)
                .connect_timeout(CONNECT_TIMEOUT)
                .retry(reqwest::retry::never())
                .redirect(reqwest::redirect::Policy::none())
                .build()
                .expect("Gmail send HTTP client should initialize"),
            base_url: gmail_url.trim_end_matches('/').to_string(),
            certs_url: jwks_url,
            contacts_url: people_url.trim_end_matches('/').to_string(),
            audience,
            subscription_topic: subscription_topic.into(),
        }
    }

    /// Lists the num_threads most recent threads for the user, optionally
    /// filtered to threads carrying all of the given Gmail label ids
    /// (an empty slice applies no filter).
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn list_threads(
        &self,
        access_token: &str,
        num_threads: u32,
        next_page_token: Option<&str>,
        label_ids: &[&str],
    ) -> Result<ListThreadsResponse, GmailApiHttpError> {
        threads::list_threads(self, access_token, num_threads, next_page_token, label_ids).await
    }

    /// Lists the `num_messages` most recent message provider ids for the user,
    /// optionally filtered to messages carrying all of the given Gmail label
    /// ids (an empty slice applies no filter). Capped at 500 by the Gmail API.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn list_messages(
        &self,
        access_token: &str,
        num_messages: u32,
        label_ids: &[&str],
    ) -> Result<Vec<String>, GmailApiHttpError> {
        list_messages(self, access_token, num_messages, label_ids).await
    }

    // Returns a list containing the message ids belonging to the thread.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_message_ids_for_thread(
        &self,
        access_token: &str,
        thread_id: &str,
    ) -> Result<Vec<String>, GmailApiHttpError> {
        threads::get_message_ids_for_thread(self, access_token, thread_id).await
    }

    /// Fetches a single thread and its messages from Gmail.
    /// Returns a raw Gmail ThreadResource - callers should map to service layer structs.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_thread(
        &self,
        access_token: &str,
        thread_id: &str,
    ) -> Result<ThreadResource, GmailApiHttpError> {
        get_thread(self, access_token, thread_id).await
    }

    /// Gets one page of the changes to a user's inbox since `start_history_id`.
    /// Pass the previous page's `next_page_token` to continue. Returns the raw
    /// HistoryListResponse; callers map it to inbox changes.
    #[tracing::instrument(skip(self, access_token, page_token), err)]
    pub async fn get_history_page(
        &self,
        access_token: &str,
        start_history_id: &str,
        page_token: Option<&str>,
    ) -> Result<HistoryListResponse, GmailApiHttpError> {
        history::get_history_page(self, access_token, start_history_id, page_token).await
    }

    /// Fetches the user's raw Gmail profile.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_profile(
        &self,
        access_token: &str,
    ) -> Result<GmailUserProfile, GmailApiHttpError> {
        profile::get_profile(self, access_token).await
    }

    /// Fetches Google's public JWKS keys used for verifying OAuth 2.0 tokens.
    #[tracing::instrument(skip(self), err)]
    pub async fn get_google_public_keys(&self) -> Result<GooglePublicKeys, GmailApiHttpError> {
        fetch_google_public_keys(self).await
    }

    /// Verifies a Google JWT token against the provided public keys
    /// Validates the token's signature, issuer, audience, and expiration time
    #[tracing::instrument(skip(self, token, public_keys), err)]
    pub fn verify_google_token(
        &self,
        token: &str,
        public_keys: KeyMap,
    ) -> std::result::Result<GoogleJwtClaims, JwtVerificationError> {
        verify_google_jwt(self, token, public_keys)
    }

    /// Registers a push notification watch on the user's inbox
    /// This will cause notifications to be sent to the subscription_topic
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn register_watch(
        &self,
        access_token: &str,
    ) -> Result<models_email::gmail::history::WatchResponse, GmailApiHttpError> {
        watch::register_watch(self, access_token).await
    }

    /// Stops push notifications by revoking the notification watch
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn stop_watch(&self, access_token: &str) -> Result<(), GmailApiHttpError> {
        watch::stop_watch(self, access_token).await
    }

    /// Adds and removes labels according to the provided lists
    #[tracing::instrument(
        skip(self, access_token),
        fields(provider_message_id = %provider_message_id),
        err
    )]
    pub async fn modify_message_labels(
        &self,
        access_token: &str,
        provider_message_id: &str,
        label_ids_to_add: &[String],
        label_ids_to_remove: &[String],
    ) -> Result<(), GmailApiHttpError> {
        labels::modify_message_labels(
            self,
            access_token,
            provider_message_id,
            label_ids_to_add,
            label_ids_to_remove,
        )
        .await
    }

    /// Adds and removes labels on many messages in one request (at most
    /// [`models_email::gmail::gmail_ops::MAX_BATCH_MODIFY_MESSAGES`] ids).
    #[tracing::instrument(
        skip(self, access_token, provider_message_ids),
        fields(message_count = provider_message_ids.len()),
        err
    )]
    pub async fn batch_modify_message_labels(
        &self,
        access_token: &str,
        provider_message_ids: &[String],
        label_ids_to_add: &[String],
        label_ids_to_remove: &[String],
    ) -> Result<(), GmailApiHttpError> {
        labels::batch_modify_message_labels(
            self,
            access_token,
            provider_message_ids,
            label_ids_to_add,
            label_ids_to_remove,
        )
        .await
    }

    /// Fetches a specific message from Gmail by its provider ID.
    /// Returns raw Gmail MessageResource - callers should map to service layer structs.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_message(
        &self,
        access_token: &str,
        message_provider_id: &str,
    ) -> Result<Option<MessageResource>, GmailApiHttpError> {
        get_message(self, access_token, message_provider_id).await
    }

    /// Fetches a message's original RFC 822 bytes, or `None` when Gmail no
    /// longer has it.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_raw_message(
        &self,
        access_token: &str,
        message_provider_id: &str,
    ) -> Result<Option<Vec<u8>>, GmailApiHttpError> {
        messages::get_raw_message(self, access_token, message_provider_id).await
    }

    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_message_label_ids(
        &self,
        access_token: &str,
        message_provider_id: &str,
    ) -> Result<Option<Vec<String>>, GmailApiHttpError> {
        get_message_label_ids(self, access_token, message_provider_id).await
    }

    /// Sends prepared MIME bytes and returns Gmail's provider identifiers.
    #[tracing::instrument(skip(self, access_token, mime), err)]
    pub async fn send_message(
        &self,
        access_token: &str,
        mime: &[u8],
        thread_id: Option<&str>,
    ) -> Result<models_email::gmail::SentMessageResource, GmailApiHttpError> {
        messages::send_message(self, access_token, mime, thread_id).await
    }

    /// Looks for a unique sent message by its RFC 5322 Message-ID, including trash.
    #[tracing::instrument(skip(self, access_token, message_id), err)]
    pub async fn find_sent_message(
        &self,
        access_token: &str,
        message_id: &str,
    ) -> Result<Option<models_email::gmail::SentMessageResource>, GmailApiHttpError> {
        messages::find_sent_message(self, access_token, message_id).await
    }

    /// Fetches an attachment from Gmail by its provider ID
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_attachment_data(
        &self,
        access_token: &str,
        message_id: &str,
        attachment_id: &str,
    ) -> Result<Vec<u8>, GmailApiHttpError> {
        attachments::get_attachment_data(self, access_token, message_id, attachment_id).await
    }

    /// Fetches user's Gmail labels
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn fetch_user_labels(
        &self,
        access_token: &str,
    ) -> Result<Vec<GmailLabel>, GmailApiHttpError> {
        labels::fetch_user_labels(self, access_token).await
    }

    /// Creates a new Gmail label from a raw Gmail label request.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn create_label(
        &self,
        access_token: &str,
        request: &GmailLabel,
    ) -> Result<GmailLabel, GmailApiHttpError> {
        labels::create_label(self, access_token, request).await
    }

    /// Deletes a Gmail label by its ID.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn delete_label(
        &self,
        access_token: &str,
        label_id: &str,
    ) -> Result<(), GmailApiHttpError> {
        labels::delete_gmail_label(self, access_token, label_id).await
    }

    /// Fetches the user's own contact information.
    /// Returns raw Gmail PersonResource - callers should map to service layer Contact.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn get_self_contact(
        &self,
        access_token: &str,
    ) -> Result<PersonResource, GmailApiHttpError> {
        get_self_connection(self, access_token).await
    }

    /// Fetches one page of the user's main contacts. Pass the previous page's
    /// `next_page_token` to continue; the last page carries the sync token for
    /// future incremental updates. Callers map the people to service contacts.
    /// Failures log at WARN: expired sync tokens and missing contacts scopes are routine.
    #[tracing::instrument(skip(self, access_token, sync_token, page_token), err(level = "warn"))]
    pub async fn get_contacts_page(
        &self,
        access_token: &str,
        sync_token: Option<&str>,
        page_token: Option<&str>,
    ) -> Result<ConnectionsResponse, GmailApiHttpError> {
        contacts::get_connections_page(self, access_token, sync_token, page_token).await
    }

    /// Fetches one page of the user's "Other Contacts", typically created from
    /// interactions. Paging and sync tokens work as in [`Self::get_contacts_page`].
    /// Failures log at WARN: expired sync tokens and missing contacts scopes are routine.
    #[tracing::instrument(skip(self, access_token, sync_token, page_token), err(level = "warn"))]
    pub async fn get_other_contacts_page(
        &self,
        access_token: &str,
        sync_token: Option<&str>,
        page_token: Option<&str>,
    ) -> Result<OtherContactsResponse, GmailApiHttpError> {
        contacts::get_other_contacts_page(self, access_token, sync_token, page_token).await
    }

    /// Creates a new Gmail filter.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn create_filter(
        &self,
        access_token: &str,
        filter: Filter,
    ) -> Result<Filter, GmailApiHttpError> {
        filters::create_filter(self, access_token, filter).await
    }

    /// Lists all filters for the user.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn list_filters(&self, access_token: &str) -> Result<Vec<Filter>, GmailApiHttpError> {
        filters::list_filters(self, access_token).await
    }

    /// Deletes a filter by ID.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn delete_filter(
        &self,
        access_token: &str,
        filter_id: &str,
    ) -> Result<(), GmailApiHttpError> {
        filters::delete_filter(self, access_token, filter_id).await
    }

    /// Lists all sendAs aliases for the user, including their signatures.
    #[tracing::instrument(skip(self, access_token), err)]
    pub async fn list_send_as(
        &self,
        access_token: &str,
    ) -> Result<models_email::gmail::ListSendAsResponse, GmailApiHttpError> {
        send_as::list_send_as(self, access_token).await
    }
}