Todoist SDK for Ruby

A comprehensive Ruby SDK for the Todoist API, providing an intuitive and elegant interface to interact with Todoist's powerful task management platform.

Table of Contents

• Installation
• Quick Start
• Authentication
• Features
• Usage
  • Tasks
  • Projects
  • Labels
  • Comments
  • Sections
  • Files
  • User
• Error Handling
• Collections
• Testing
• Contributing
• License

Installation

Add this line to your application's Gemfile:

gem 'todoist-sdk'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install todoist-sdk

Quick Start

require 'todoist'

# Initialize the client with your Todoist API token
client = Todoist::Client.new('your_api_token_here')

# Create a new task
task = client.task.add(content: 'Buy groceries', project_id: '2ctzJkzNQ3FhGV5r')

# Get all projects
projects = client.projects.all

# Mark task as complete
client.task.complete(id: task.id)

Authentication

To use this SDK, you need a Todoist API token. You can obtain one by:

1. Going to Todoist Settings
2. Scrolling down to the "API token" section
3. Copying your API token

client = Todoist::Client.new('your_api_token_here')

Features

✅ Complete API Coverage - Supports all major Todoist API endpoints
✅ Intuitive Ruby API - Clean, Ruby-like method names and conventions
✅ Entity Objects - Rich objects with attribute access
✅ Collections - Enumerable collections for easy iteration
✅ Error Handling - Comprehensive error handling and validation
✅ File Uploads - Support for file attachments
✅ Well Tested - Comprehensive test coverage
✅ Ruby 3.0+ - Modern Ruby version support

Supported Resources

• Tasks - Create, read, update, delete, search, complete, and move tasks
• Projects - Manage projects and project hierarchy
• Labels - Create and manage labels for organization
• Comments - Add comments to tasks and projects
• Sections - Organize tasks within projects using sections
• Files - Upload and manage file attachments
• User - Access user profile information

Usage

Tasks

The task resource provides comprehensive task management capabilities:

# Create a new task
task = client.task.add(
  content: 'Complete project proposal',
  description: 'Need to finish by end of week',
  project_id: '2ctzJkzNQ3FhGV5r',
  labels: ['work', 'urgent'],
  priority: 4,
  due_string: 'tomorrow at 9am'
)

# Get all tasks
tasks = client.task.all
tasks.each do |task|
  puts "#{task.content} - Priority: #{task.priority}"
end

# Get tasks with label
urgent_tasks = client.task.all(label: 'work')

# Update a task
updated_task = client.task.update(
  id: task.id,
  content: 'Updated task content'
)

# Get a specific task
task = client.task.retrieve(id: '7qzPm8NxR6KvGc4F')

# Search tasks
search_results = client.task.search(query: 'search: shopping')
search_results = client.task.search(query: 'date: tom')
search_results = client.task.search(query: 'no date')
search_results = client.task.search(query: 'deadline: today')
search_results = client.task.search(query: 'p1')
search_results = client.task.search(query: '@email')
search_results = client.task.search(query: '#work')
search_results = client.task.search(query: '/Meetings')
search_results = client.task.search(query: 'created: Jan 3 2023')
search_results = client.task.search(query: '(P1 | P2) & 14 days')

Note: The search method accepts any filters that Todoist supports. Check the Todoist filter documentation for all available filter options.

# Complete a task
client.task.complete(id: task.id)

# Reopen a completed task
client.task.uncomplete(id: task.id)

# Move task to different project
client.task.move(id: task.id, project_id: '9mKp5rX3Nz8QwC2v')

# Get completed tasks by completion date
completed_tasks = client.task.completed_by_completion_date(
  from: '2024-01-01',
  to: '2024-01-31'
)

# Get completed tasks by due date
completed_by_due = client.task.completed_by_due_date(
  from: '2024-01-01',
  to: '2024-01-31'
)

# Delete a task
client.task.delete(id: task.id)

Projects

Manage your project hierarchy and organization:

# Get all projects
projects = client.projects.all

# Create a new project
project = client.projects.add(
  name: 'Website Redesign',
  color: 'blue',
  is_favorite: true
)

# Get a specific project
project = client.projects.retrieve(id: '2ctzJkzNQ3FhGV5r')

# Update a project
updated_project = client.projects.update(
  id: project.id,
  name: 'Updated Project Name',
  color: 'red'
)

# Delete a project
client.projects.delete(id: project.id)

Labels

Create and manage labels for better task organization:

# Get all labels
labels = client.label.all

# Create a new label
label = client.label.add(
  name: 'urgent',
  color: 'red'
)

# Get a specific label
label = client.label.retrieve(id: '5wNpR9KxM2VbGh8Q')

# Update a label
updated_label = client.label.update(
  id: label.id,
  name: 'high-priority',
  color: 'orange'
)

# Delete a label
client.label.delete(id: label.id)

Comments

Add comments to tasks and projects for collaboration:

# Add a comment to a task
comment = client.comment.add(
  content: 'This task is almost complete!',
  id: '7qzPm8NxR6KvGc4F'
)

# Add a comment to a project
project_comment = client.comment.add(
  content: 'Project is on track',
  project_id: '2ctzJkzNQ3FhGV5r'
)

# Get all comments for a task
task_comments = client.comment.all(id: '7qzPm8NxR6KvGc4F')

# Get all comments for a project
project_comments = client.comment.all(project_id: '2ctzJkzNQ3FhGV5r')

# Get a specific comment
comment = client.comment.retrieve(id: '8pKx6wQ4NmVhRz5T')

# Update a comment
updated_comment = client.comment.update(
  id: comment.id,
  content: 'Updated comment content'
)

# Delete a comment
client.comment.delete(id: comment.id)

Sections

Organize tasks within projects using sections:

# Get all sections
sections = client.section.all

# Create a new section
section = client.section.add(
  name: 'In Progress',
  project_id: '2ctzJkzNQ3FhGV5r'
)

# Get a specific section
section = client.section.retrieve(id: '6vFg9rP2KnMx4WbH')

# Update a section
updated_section = client.section.update(
  id: section.id,
  name: 'Completed Tasks'
)

# Delete a section
client.section.delete(id: section.id)

Files

Upload and manage file attachments:

# Upload a file
uploaded_file = client.file.upload(file_path: '/path/to/your/file.pdf')

# Delete a file
client.file.delete(file_url: uploaded_file.file_url)

Attach file to project or comment:

file = client.file.upload(file_path: '/path/to/your/file.pdf')
client.comment.add(
	content: 'Comment with attachment',
	project_id: '2ctzJkzNQ3FhGV5r',
	attachment: file.to_h
)

User

Access user profile information:

# Get current user information
user = client.user.info

puts "User: #{user.full_name}"
puts "Email: #{user.email}"
puts "Premium: #{user.is_premium}"
puts "Timezone: #{user.tz_info.timezone}"

Error Handling

The SDK provides comprehensive error handling for API errors:

begin
  task = client.task.add(content: 'New task')
rescue Todoist::Error => e
  puts "API Error: #{e.message}"
end

Common error scenarios:

• Invalid API token
• Rate limiting
• Invalid request parameters
• Resource not found
• Network connectivity issues

Collections

The SDK returns collections for list operations that implement Ruby's Enumerable interface:

tasks = client.task.all

# Iterate through tasks
tasks.each do |task|
  puts task.content
end

# Use Enumerable methods
urgent_tasks = tasks.select { |task| task.priority == 4 }
task_contents = tasks.map(&:content)

# Check collection size
puts "Total tasks: #{tasks.count}"

# Access pagination info (if available)
puts "Next cursor: #{tasks.next_cursor}" if tasks.next_cursor

Testing

The gem includes comprehensive test coverage using Minitest and WebMock. To run the tests:

$ bundle exec rake test

Running Tests in Development

# Run all tests
$ rake test

# Run specific test file
$ ruby -Itest test/resources/task_resource_test.rb

API Coverage

This SDK covers all major Todoist API v1 endpoints:

Resource	Create	Read	Update	Delete	Additional Operations
Tasks	✅	✅	✅	✅	Complete, Search, Move, Get Completed
Projects	✅	✅	✅	✅	-
Labels	✅	✅	✅	✅	-
Comments	✅	✅	✅	✅	-
Sections	✅	✅	✅	✅	-
Files	✅	-	-	✅	Upload
User	-	✅	-	-	Get Profile

Requirements

• Ruby 3.0 or higher
• A valid Todoist API token

ID Format Compatibility

This SDK supports both Todoist ID formats:

• V2 IDs (current): '2ctzJkzNQ3FhGV5r' - Recommended for new integrations
• V1 IDs (legacy): '123456789' - Still supported but being phased out

All examples in this documentation use the current V2 ID format.

Dependencies

This gem has minimal dependencies:

• json (standard library)
• net/http (standard library)
• uri (standard library)

Development dependencies:

• minitest for testing
• rake for task management
• webmock for HTTP request stubbing

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Make your changes and ensure tests pass
5. Commit your changes (git commit -am 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Create a Pull Request

Development Setup

$ git clone https://github.com/msaami/todoist-sdk.git
$ cd todoist-sdk
$ bundle install
$ bundle exec rake test

License

This gem is available as open source under the terms of the MIT License.

Support

• Documentation: Todoist API Documentation
• Issues: GitHub Issues
• Email: [email protected]

Changelog

v0.1.0

• Initial release
• Support for all major Todoist API endpoints
• Comprehensive test coverage
• Ruby 3.0+ support

---

Built with ❤️ for the Ruby community by Mehrdad Sami