📝 docs(lib): rename lib.md and update code block formatting
- 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.
This commit is contained in:
committed by
Jeremiah Russell
parent
40cfa2a223
commit
eac99bddbc
@@ -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
|
||||
Reference in New Issue
Block a user