Todoist-api
A comprehensive Rust wrapper for the Todoist REST API v2, providing a clean and ergonomic interface for managing tasks, projects, labels, sections, and comments.
Features
- 🚀 Async/await support - Built with Tokio for high-performance async operations
- 📝 Full CRUD operations - Create, read, update, and delete all Todoist entities
- 🏗️ Project management - Complete project lifecycle management
- 🏷️ Label support - Full label operations with filtering
- 📋 Section management - Organize projects with sections
- 💬 Comment system - Add and manage comments on tasks and projects
- 🔍 Advanced filtering - Filter tasks, projects, and labels with pagination
- 🔒 Type safety - Full Rust type safety with Serde serialization
- 🛡️ Error handling - Comprehensive error handling with anyhow
- 📚 Well documented - Extensive documentation and examples
Installation
Add this to your Cargo.toml
:
[]
= "0.1.0"
Quick Start
use TodoistWrapper;
async
API Reference
Creating a Client
let todoist = new;
Task Operations
// Get all tasks
let tasks = todoist.get_tasks.await?;
// Get a specific task
let task = todoist.get_task.await?;
// Get tasks for a specific project
let project_tasks = todoist.get_tasks_for_project.await?;
// Get tasks by filter query
let filter_args = TaskFilterArgs ;
let filtered_tasks = todoist.get_tasks_by_filter.await?;
// Create a simple task
let task = todoist.create_simple_task.await?;
// Create a task with full options
let create_args = CreateTaskArgs ;
let task = todoist.create_task.await?;
// Update a task
let update_args = UpdateTaskArgs ;
let updated_task = todoist.update_task.await?;
// Complete a task
todoist.complete_task.await?;
// Reopen a completed task
todoist.reopen_task.await?;
// Delete a task
todoist.delete_task.await?;
Project Operations
// Get all projects
let projects = todoist.get_projects.await?;
// Get a specific project
let project = todoist.get_project.await?;
// Get projects with filtering
let filter_args = ProjectFilterArgs ;
let filtered_projects = todoist.get_projects_filtered.await?;
// Create a new project
let create_args = CreateProjectArgs ;
let project = todoist.create_project.await?;
// Update a project
let update_args = UpdateProjectArgs ;
let updated_project = todoist.update_project.await?;
// Delete a project
todoist.delete_project.await?;
Label Operations
// Get all labels
let labels = todoist.get_labels.await?;
// Get a specific label
let label = todoist.get_label.await?;
// Get labels with filtering
let filter_args = LabelFilterArgs ;
let filtered_labels = todoist.get_labels_filtered.await?;
// Create a new label
let create_args = CreateLabelArgs ;
let label = todoist.create_label.await?;
// Update a label
let update_args = UpdateLabelArgs ;
let updated_label = todoist.update_label.await?;
// Delete a label
todoist.delete_label.await?;
Section Operations
// Get all sections
let sections = todoist.get_sections.await?;
// Get a specific section
let section = todoist.get_section.await?;
// Get sections for a project
let filter_args = SectionFilterArgs ;
let project_sections = todoist.get_sections_filtered.await?;
// Create a new section
let create_args = CreateSectionArgs ;
let section = todoist.create_section.await?;
// Update a section
let update_args = UpdateSectionArgs ;
let updated_section = todoist.update_section.await?;
// Delete a section
todoist.delete_section.await?;
Comment Operations
// Get all comments
let comments = todoist.get_comments.await?;
// Get a specific comment
let comment = todoist.get_comment.await?;
// Get comments for a task
let filter_args = CommentFilterArgs ;
let task_comments = todoist.get_comments_filtered.await?;
// Create a new comment
let create_args = CreateCommentArgs ;
let comment = todoist.create_comment.await?;
// Update a comment
let update_args = UpdateCommentArgs ;
let updated_comment = todoist.update_comment.await?;
// Delete a comment
todoist.delete_comment.await?;
Data Models
The library provides comprehensive data models for all Todoist entities:
Task
- Complete task information with all fieldsProject
- Project details and metadataLabel
- Label information and stylingSection
- Section organization within projectsComment
- Comment system for tasks and projectsAttachment
- File attachments for commentsUser
- User information and preferencesDue
- Due date and time informationDeadline
- Deadline informationDuration
- Task duration tracking
Argument Types
For flexible API operations, the library provides argument types:
CreateTaskArgs
- Full task creation optionsUpdateTaskArgs
- Task update parametersCreateProjectArgs
- Project creation optionsUpdateProjectArgs
- Project update parametersCreateLabelArgs
- Label creation optionsUpdateLabelArgs
- Label update parametersCreateSectionArgs
- Section creation optionsUpdateSectionArgs
- Section update parametersCreateCommentArgs
- Comment creation optionsUpdateCommentArgs
- Comment update parameters
Filter Types
For advanced querying and pagination:
TaskFilterArgs
- Task filtering and paginationProjectFilterArgs
- Project filtering and paginationLabelFilterArgs
- Label filtering and paginationSectionFilterArgs
- Section filtering and paginationCommentFilterArgs
- Comment filtering and pagination
Error Handling
All operations return anyhow::Result<T>
, providing comprehensive error handling:
match todoist.get_tasks.await
Configuration
The library uses sensible defaults:
- 10-second timeout for HTTP requests
- Automatic retry with fallback to default client
- Bearer token authentication
- Comprehensive error handling
Testing
The library includes a comprehensive test suite covering all functionality:
Test Coverage
- Unit Tests: 47 tests covering all models, argument types, and core functionality
- Integration Tests: 10 tests for complete workflows (can be run with real API access)
- ** Documentation Tests**: Ensures all examples compile and run correctly
Running Tests
# Run all tests
# Run only unit tests (no API access required)
# Run specific test suites
# Run with verbose output
# Run ignored tests (requires API token)
Test Configuration
Set the following environment variables to run integration tests:
Test Structure
tests/
├── models_tests.rs # Data model validation tests
├── wrapper_tests.rs # API wrapper functionality tests
├── integration_tests.rs # End-to-end workflow tests
├── common/
│ └── mod.rs # Test utilities and helpers
└── config.rs # Test configuration management
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Changelog
0.1.0
- Initial release
- Complete CRUD operations for all Todoist entities
- Advanced filtering and pagination support
- Comprehensive data models
- Async/await support
- Comprehensive error handling
Roadmap
- Task filtering and search
- Complete API coverage
- Advanced filtering and pagination
- Section and comment management
- OAuth2 authentication support
- Webhook support
- Rate limiting and retry logic
- Batch operations