grenade/cull-gmail
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(message-list): document trait and public methods with examples and error semantics

Browse Source
This commit is contained in:
Jeremiah Russell
2025-10-19 22:33:19 +01:00
committed by Jeremiah Russell
parent 257caf55ab
commit 501d8a5830
1 changed files with 264 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

277
src/message_list.rs
View File

@@ -60,34 +60,285 @@ use google_gmail1::{
hyper_util::client::legacy::connect::HttpConnector,
};
/// Methods to select lists of messages from the mailbox
/// A trait for interacting with Gmail message lists, providing methods for
/// retrieving, filtering, and managing collections of Gmail messages.
///
/// This trait abstracts the core operations needed to work with Gmail message lists,
/// including pagination, filtering by labels and queries, and configuring result limits.
///
/// # Examples
///
/// ```rust,no_run
/// use cull_gmail::{MessageList, GmailClient, ClientConfig};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let config = ClientConfig::builder().build();
/// let mut client = GmailClient::new_with_config(config).await?;
///
/// // Set search parameters
/// client.set_query("is:unread");
/// client.set_max_results(100);
///
/// // Retrieve first page of messages
/// client.get_messages(1).await?;
/// # Ok(())
/// # }
/// ```
pub trait MessageList {
/// Log the initial characters of the subjects of the message in the list
/// Fetches detailed metadata for stored messages and logs their subjects and dates.
///
/// This method retrieves the subject line and date for each message currently
/// stored in the message list and outputs them to the log.
///
/// # Returns
///
/// Returns `Result<()>` on success, or an error if the Gmail API request fails.
///
/// # Errors
///
/// This method can fail if:
/// - The Gmail API is unreachable
/// - Authentication credentials are invalid or expired
/// - Network connectivity issues occur
/// - Individual message retrieval fails
fn log_messages(&mut self) -> impl std::future::Future<Output = Result<()>> + Send;
/// List of messages
/// Retrieves a list of messages from Gmail based on current filter settings.
///
/// This method calls the Gmail API to get a page of messages matching the
/// configured query and label filters. Retrieved message IDs are stored
/// internally for further operations.
///
/// # Arguments
///
/// * `next_page_token` - Optional token for pagination. Use `None` for the first page,
/// or the token from a previous response to get subsequent pages.
///
/// # Returns
///
/// Returns the raw `ListMessagesResponse` from the Gmail API, which contains
/// message metadata and pagination tokens.
///
/// # Errors
///
/// This method can fail if:
/// - The Gmail API request fails
/// - Authentication is invalid
/// - The query syntax is malformed
/// - Network issues prevent the API call
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::{MessageList, GmailClient, ClientConfig};
/// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> {
/// // Get the first page of results
/// let response = client.list_messages(None).await?;
///
/// // Get the next page if available
/// if let Some(token) = response.next_page_token {
/// let next_page = client.list_messages(Some(token)).await?;
/// }
/// # Ok(())
/// # }
/// ```
fn list_messages(
&mut self,
next_page_token: Option<String>,
) -> impl std::future::Future<Output = Result<ListMessagesResponse>> + Send;
/// Run something
/// Retrieves multiple pages of messages based on the specified page limit.
///
/// This method handles pagination automatically, fetching the specified number
/// of pages or all available pages if `pages` is 0.
///
/// # Arguments
///
/// * `pages` - Number of pages to retrieve:
/// - `0`: Fetch all available pages
/// - `1`: Fetch only the first page
/// - `n > 1`: Fetch exactly `n` pages or until no more pages are available
///
/// # Returns
///
/// Returns `Result<()>` on success. All retrieved messages are stored internally
/// and can be accessed via `messages()`.
///
/// # Errors
///
/// This method can fail if any individual page request fails. See `list_messages`
/// for specific error conditions.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::{MessageList, GmailClient, ClientConfig};
/// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> {
/// // Get all available pages
/// client.get_messages(0).await?;
///
/// // Get exactly 3 pages
/// client.get_messages(3).await?;
/// # Ok(())
/// # }
/// ```
fn get_messages(&mut self, pages: u32) -> impl std::future::Future<Output = Result<()>> + Send;
/// Return the gmail hub
/// Returns a reference to the Gmail API hub for direct API access.
///
/// This method provides access to the underlying Gmail API client for
/// advanced operations not covered by this trait.
///
/// # Returns
///
/// A cloned `Gmail` hub instance configured with the appropriate connectors.
fn hub(&self) -> Gmail<HttpsConnector<HttpConnector>>;
/// Return the list of label_ids
/// Returns the list of label IDs currently configured for message filtering.
///
/// # Returns
///
/// A vector of Gmail label ID strings. These IDs are used to filter
/// messages during API calls.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(client: impl MessageList) {
/// let labels = client.label_ids();
/// println!("Filtering by {} labels", labels.len());
/// # }
/// ```
fn label_ids(&self) -> Vec<String>;
/// Return the list of message ids
/// Returns a list of message IDs for all currently stored messages.
///
/// # Returns
///
/// A vector of Gmail message ID strings. These IDs can be used for
/// further Gmail API operations on specific messages.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(client: impl MessageList) {
/// let message_ids = client.message_ids();
/// println!("Found {} messages", message_ids.len());
/// # }
/// ```
fn message_ids(&self) -> Vec<String>;
/// Return a summary of the messages (id and summary)
/// Returns a reference to the collection of message summaries.
///
/// This method provides access to all message summaries currently stored,
/// including any metadata that has been fetched.
///
/// # Returns
///
/// A reference to a vector of `MessageSummary` objects containing
/// message IDs and any retrieved metadata.
fn messages(&self) -> &Vec<MessageSummary>;
/// Set the query for the message list
/// Sets the search query string for filtering messages.
///
/// This method configures the Gmail search query that will be used in
/// subsequent API calls. The query uses Gmail's search syntax.
///
/// # Arguments
///
/// * `query` - A Gmail search query string (e.g., "is:unread", "from:example@gmail.com")
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(mut client: impl MessageList) {
/// client.set_query("is:unread older_than:30d");
/// client.set_query("from:noreply@example.com");
/// # }
/// ```
fn set_query(&mut self, query: &str);
/// Add label ids to the list of labels for the message list
/// Adds Gmail label IDs to the current filter list.
///
/// This method appends the provided label IDs to the existing list of
/// labels used for filtering messages. Messages must match ALL specified labels.
///
/// # Arguments
///
/// * `label_ids` - A slice of Gmail label ID strings to add to the filter
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(mut client: impl MessageList) {
/// let label_ids = vec!["Label_1".to_string(), "Label_2".to_string()];
/// client.add_labels_ids(&label_ids);
/// # }
/// ```
fn add_labels_ids(&mut self, label_ids: &[String]);
/// Add labels to the list of labels for the message list
/// Adds Gmail labels by name to the current filter list.
///
/// This method resolves label names to their corresponding IDs and adds them
/// to the filter list. This is more convenient than using `add_labels_ids`
/// when you know the label names but not their IDs.
///
/// # Arguments
///
/// * `labels` - A slice of Gmail label name strings (e.g., "INBOX", "SPAM")
///
/// # Returns
///
/// Returns `Result<()>` on success, or an error if label name resolution fails.
///
/// # Errors
///
/// This method can fail if label name to ID resolution is not available
/// or if the underlying label ID mapping is not accessible.
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # async fn example(mut client: impl MessageList) -> cull_gmail::Result<()> {
/// let labels = vec!["INBOX".to_string(), "IMPORTANT".to_string()];
/// client.add_labels(&labels)?;
/// # Ok(())
/// # }
/// ```
fn add_labels(&mut self, labels: &[String]) -> Result<()>;
/// Report the max results value set
/// Returns the current maximum results limit per API request.
///
/// # Returns
///
/// The maximum number of messages to retrieve in a single API call.
/// Default is typically 200.
fn max_results(&self) -> u32;
/// Set the max_results value
/// Sets the maximum number of results to return per API request.
///
/// This controls how many messages are retrieved in each page when calling
/// the Gmail API. Larger values reduce the number of API calls needed but
/// increase memory usage and response time.
///
/// # Arguments
///
/// * `value` - Maximum results per page (typically 1-500, Gmail API limits apply)
///
/// # Examples
///
/// ```rust,no_run
/// # use cull_gmail::MessageList;
/// # fn example(mut client: impl MessageList) {
/// client.set_max_results(100); // Retrieve 100 messages per page
/// client.set_max_results(500); // Retrieve 500 messages per page (maximum)
/// # }
/// ```
fn set_max_results(&mut self, value: u32);
}