From eac99bddbc5880fbd10abc38e257bb8bcdf29f37 Mon Sep 17 00:00:00 2001 From: Jeremiah Russell Date: Fri, 17 Oct 2025 17:22:44 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(lib):=20rename=20lib.md=20a?= =?UTF-8?q?nd=20update=20code=20block=20formatting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Renamed `docs/readme/lib.md` to `docs/lib/lib.md` for better file structure. - Updated code blocks to remove `path=null start=null` for cleaner rendering. --- docs/{readme => lib}/lib.md | 118 +++--------------------------------- 1 file changed, 8 insertions(+), 110 deletions(-) rename docs/{readme => lib}/lib.md (62%) diff --git a/docs/readme/lib.md b/docs/lib/lib.md similarity index 62% rename from docs/readme/lib.md rename to docs/lib/lib.md index 0c4f184..bd7e381 100644 --- a/docs/readme/lib.md +++ b/docs/lib/lib.md @@ -16,7 +16,7 @@ tokio = { version = "1.0", features = ["macros", "rt-multi-thread"] } Here's a minimal example to get started: -```rust path=null start=null +```rust use cull_gmail::{ClientConfig, GmailClient, Result}; #[tokio::main] @@ -44,7 +44,7 @@ async fn main() -> Result<()> { The main client for interacting with Gmail API: -```rust path=null start=null +```rust use cull_gmail::{GmailClient, MessageList}; // Create client with configuration @@ -67,7 +67,7 @@ let message_ids = client.message_ids(); Handles authentication and configuration: -```rust path=null start=null +```rust use cull_gmail::ClientConfig; // From credential file @@ -90,7 +90,7 @@ let config = ClientConfig::builder() Define automated message lifecycle rules: -```rust path=null start=null +```rust use cull_gmail::{Rules, Retention, MessageAge, EolAction}; // Create a rule set @@ -120,7 +120,7 @@ let loaded_rules = Rules::load()?; Batch operations on messages: -```rust path=null start=null +```rust use cull_gmail::{RuleProcessor, EolAction}; // Set up rule and dry-run mode @@ -156,7 +156,7 @@ match client.action() { 2. Download the credential JSON file 3. Configure the client: -```rust path=null start=null +```rust let config = ClientConfig::builder() .with_credential_file("path/to/credential.json") .build(); @@ -194,7 +194,7 @@ export APP_CLIENT_SECRET="your-client-secret" The library uses a comprehensive error type: -```rust path=null start=null +```rust use cull_gmail::{Error, Result}; match client.get_messages(1).await { @@ -223,7 +223,7 @@ The library requires an async runtime (Tokio recommended): tokio = { version = "1.0", features = ["macros", "rt-multi-thread"] } ``` -```rust path=null start=null +```rust #[tokio::main] async fn main() -> cull_gmail::Result<()> { // Your code here @@ -231,105 +231,3 @@ async fn main() -> cull_gmail::Result<()> { } ``` -## Gmail Query Syntax - -The library supports Gmail's search syntax for message queries: - -```rust path=null start=null -// Date-based queries -client.set_query("older_than:1y"); // Older than 1 year -client.set_query("newer_than:30d"); // Newer than 30 days -client.set_query("after:2023/1/1"); // After specific date - -// Label-based queries -client.set_query("label:promotions"); // Has promotions label -client.set_query("-label:important"); // Does NOT have important label - -// Content queries -client.set_query("subject:newsletter"); // Subject contains "newsletter" -client.set_query("from:noreply@example.com"); // From specific sender - -// Combined queries -client.set_query("label:promotions older_than:6m -is:starred"); -``` - -## Performance & Limits - -### Pagination - -- Default page size: 200 messages -- Use `client.set_max_results(n)` to adjust -- Use `client.get_messages(0)` to get all pages -- Use `client.get_messages(n)` to limit to n pages - -### Rate Limits - -- The library uses the official `google-gmail1` crate -- Built-in retry logic for transient errors -- Respects Gmail API quotas and limits - -### Batch Operations - -- Batch delete/trash operations are more efficient than individual calls -- Operations are atomic - either all succeed or all fail - -## Logging - -The library uses the `log` crate for logging: - -```rust path=null start=null -use env_logger; - -// Initialize logging -env_logger::init(); - -# Set log level via environment variable -# RUST_LOG=cull_gmail=debug cargo run -``` - -Log levels: -- `error`: Critical errors -- `warn`: Warnings (e.g., missing labels, dry-run mode) -- `info`: General information (e.g., message subjects, action results) -- `debug`: Detailed operation info -- `trace`: Very detailed debugging info - -## Security Considerations - -### OAuth2 Token Storage -- Tokens are stored in `~/.cull-gmail/gmail1` by default -- Tokens are automatically refreshed when expired -- Revoke access in [Google Account settings](https://myaccount.google.com/permissions) - -### Required Scopes -The library requires the `https://mail.google.com/` scope for full Gmail access. - -### Credential File Security -- Store credential files securely (not in version control) -- Use restrictive file permissions (600) -- Consider using environment variables in production - -## Troubleshooting - -### Authentication Issues -1. Verify credential file path and format -2. Check OAuth2 client is configured for "Desktop Application" -3. Ensure redirect URI matches configuration -4. Clear token cache: `rm -rf ~/.cull-gmail/gmail1` - -### No Messages Found -1. Verify label names exist: `client.show_label()` -2. Test query syntax in Gmail web interface -3. Check for typos in label names or query strings - -### Rate Limiting -1. Reduce page size: `client.set_max_results(100)` -2. Add delays between operations -3. Check [Gmail API quotas](https://developers.google.com/gmail/api/reference/quota) - -## See Also - -- [CLI Documentation](main.md) - Complete guide to the command-line interface -- [Examples Directory](../examples/) - Additional code examples and sample configurations -- [API Documentation](https://docs.rs/cull-gmail) - Generated API reference -- [Repository](https://github.com/jerus-org/cull-gmail) - Source code and issue tracking