clickup_v2

A comprehensive Rust client library and CLI for the ClickUp API v2, featuring OAuth2 authentication, full task management with custom fields support, and intelligent caching.

Features

• Complete OAuth2 Flow: Secure authentication with automatic token management
• Multi-Environment Support: Seamlessly works in development (local) and production (cloud) environments
• Task Management: Create, read, update, and delete tasks with full custom field support
• Entity Search: Search spaces, folders, lists, and tasks with intelligent caching (3-hour TTL)
• CLI Tool: Powerful command-line interface for all operations
• Type Safety: Fully typed API with comprehensive error handling
• Async/Await: Modern async Rust with Tokio runtime

Installation

As a Library

Add to your Cargo.toml:

[dependencies]
clickup_v2 = "0.1.0"

As a CLI Tool

Install directly from crates.io:

cargo install clickup_v2

Or clone and build locally:

git clone https://github.com/yourusername/clickup_v2.git
cd clickup_v2
cargo install --path .

Quick Start

Library Usage

use clickup_v2::{ClickUpClient, auth::OAuthFlow};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Authenticate and get access token
    let oauth = OAuthFlow::new()?;
    let token = oauth.authenticate().await?;

    // Create client
    let client = ClickUpClient::new(token, None);

    // Get user info
    let user = client.get_authorized_user().await?;
    println!("Authenticated as: {}", user["username"]);

    // Create a task with custom fields
    let task = client.create_task(
        "list_id",
        CreateTaskRequest::builder()
            .name("New Feature")
            .content("Implement OAuth2 flow")
            .priority(2)
            .custom_field("field_id", CustomFieldValue::Text("In Progress".to_string()))
            .build()
    ).await?;

    Ok(())
}

CLI Usage

# Authenticate (first time setup)
clickup_v2 login

# Get user info
clickup_v2 user

# List all workspaces
clickup_v2 list-teams

# Create a task
clickup_v2 create-task \
  --list-id "123456" \
  --name "New Feature" \
  --content "Implement new functionality" \
  --priority 2 \
  --custom-field "field_123:text:In Progress"

# Search for entities
clickup_v2 search --name "My Project" --type folder

# Get tasks from a list
clickup_v2 get-tasks --list-id "123456"

Environment Setup

Development Environment

Create a .env file in your project root:

# OAuth2 Credentials (required)
CLICKUP_CLIENT_ID=your_client_id
CLICKUP_CLIENT_SECRET=your_client_secret
CLICKUP_REDIRECT_URI=http://localhost:8888/callback

# Optional
CLICKUP_TEAM_ID=your_default_team_id
CLICKUP_API_URL=https://api.clickup.com/api/v2  # Custom API URL if needed

# Auto-populated after authentication
CLICKUP_ACCESS_TOKEN=your_access_token

The crate will automatically generate a template .env file if missing when you run it.

Production Environment

Set environment variables directly:

export CLICKUP_CLIENT_ID=your_client_id
export CLICKUP_CLIENT_SECRET=your_client_secret
export CLICKUP_REDIRECT_URI=https://your-app.com/callback
export CLICKUP_ACCESS_TOKEN=your_token  # Pre-authorized token

The crate automatically detects cloud environments (Google Cloud, AWS, Azure) and adjusts behavior accordingly.

Custom Fields Support

The library supports all ClickUp custom field types:

use clickup_v2::CustomFieldValue;

// Text field
CustomFieldValue::Text("In Progress".to_string())

// Number field
CustomFieldValue::Number(42.5)

// Date field (Unix timestamp in milliseconds)
CustomFieldValue::Date(1704067200000)

// Dropdown
CustomFieldValue::DropdownOption("option_id".to_string())

// Multiple options
CustomFieldValue::DropdownOptions(vec!["id1".to_string(), "id2".to_string()])

// Checkbox
CustomFieldValue::Checkbox(true)

// Rating (1-5)
CustomFieldValue::Rating(4)

// And more: Email, Phone, URL, Location, etc.

API Coverage

Authentication

• OAuth2 flow with PKCE
• Token management and refresh
• Multi-environment support

User & Teams

• Get authorized user
• Get authorized teams/workspaces

Hierarchy Navigation

• Get/Search spaces
• Get/Search folders
• Get/Search lists
• Get/Search tasks

Task Management

• Create tasks with custom fields
• Update tasks
• Delete tasks
• Get task details

Caching

• 3-hour TTL cache for entity searches
• Cache invalidation
• Cache statistics

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment:

Automated Testing

• Multi-OS Testing: Ubuntu, macOS, Windows
• Rust Versions: Stable and Beta channels
• Security Audits: Automatic vulnerability scanning
• Code Quality: Rustfmt and Clippy checks

Automatic Publication

The crate is automatically published to crates.io when:

1. Version is bumped in Cargo.toml
2. Changes are pushed to the main branch
3. All tests pass

Manual Release

For manual releases:

1. Update version in Cargo.toml
2. Push to main branch
3. CI/CD will automatically:
   • Run tests
   • Create git tag
   • Publish to crates.io
   • Create GitHub release

Setting up CI/CD

1. Add these secrets to your GitHub repository:

   • CRATES_IO_TOKEN: Your crates.io API token
   • CLICKUP_CLIENT_ID: For running tests (optional)
   • CLICKUP_CLIENT_SECRET: For running tests (optional)
   • CLICKUP_ACCESS_TOKEN: For running tests (optional)

2. The workflows will automatically run on:

   • Push to main/master/develop branches
   • Pull requests
   • Manual workflow dispatch

Development

Building from Source

# Clone the repository
git clone https://github.com/yourusername/clickup_v2.git
cd clickup_v2

# Build the project
cargo build

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run

# Run clippy
cargo clippy

# Format code
cargo fmt

Running Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_create_task

# Run integration tests (requires .env)
cargo test --features integration-tests

Debugging OAuth Flow

Enable debug logging to troubleshoot authentication:

RUST_LOG=debug cargo run

Key log markers:

• 🔑 Starting authentication - Auth flow begins
• 🌐 Authorization URL generated - OAuth URL created
• ⏳ Waiting for authorization - Callback server ready
• ✅ Authorization code received - Callback successful
• 🔄 Exchanging code for token - Token exchange

Architecture

Module Structure

src/
├── auth/
│   ├── oauth.rs      # OAuth2 flow orchestration
│   ├── callback.rs   # Local callback server
│   └── token.rs      # Token management
├── client/
│   └── api.rs        # ClickUp API client
├── config/
│   └── env.rs        # Environment configuration
├── error/
│   └── auth_error.rs # Error types
├── lib.rs            # Library interface
└── main.rs           # CLI implementation

Key Design Patterns

• Builder Pattern: Request construction
• Type State Pattern: OAuth flow states
• Repository Pattern: Token persistence
• Strategy Pattern: Environment detection

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run cargo fmt and cargo clippy
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs.rs

Acknowledgments

Built with these amazing Rust crates:

• reqwest - HTTP client
• tokio - Async runtime
• oauth2 - OAuth2 implementation
• clap - CLI parsing
• serde - Serialization

Changelog

See CHANGELOG.md for version history.

Note: Replace yourusername with your actual GitHub username in URLs and badges.