📝 docs(lib): remove gmail query syntax and troubleshooting
- remove gmail query syntax - remove performance & limits - remove logging - remove security considerations - remove troubleshooting - remove see also
This commit is contained in:
committed by
Jeremiah Russell
parent
a5ea370af2
commit
4aa47173c4
102
docs/lib.md
102
docs/lib.md
@@ -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