gtasks_core

gtasks_core is an offline-first, thread-safe Rust SDK and engine for the Google Tasks API.

Designed as the core foundation for terminal (TUI) and graphical (GUI) task managers, gtasks_core provides zero-hassle OAuth 2.0 PKCE authentication, automatic OS keyring credential persistence, thread-safe SQLite local caching, background delta synchronization, and natural-language date parsing.

✨ Features

• 🔐 Automatic OAuth 2.0 + PKCE: Handles the browser authentication handshake and securely persists refresh tokens in system secret stores (D-Bus Secret Service, KWallet, macOS Keychain).
• 🔄 Bidirectional Delta Synchronization: Periodically synchronizes remote modifications using updatedMin RFC3339 timestamps while maintaining local dirty states for offline operations.
• 📴 Offline-First SQLite Cache: High-performance, thread-safe SQLite persistence layer powered by rusqlite for local read/write performance.
• 🌲 Subtask Tree Ordering: Processes flat API responses into hierarchical parent-child task structures while maintaining custom visual ordering.
• 🧠 Natural Language Processing (NLP): Built-in date parser extracting temporal expressions like "today", "tomorrow", or "next monday" directly from task titles.
• ⚡ Actor-Based Background Sync: Non-blocking async SyncManager actor for background sync polling and window focus triggers.

📦 Installation

Add gtasks_core to your Cargo.toml:

[dependencies]
gtasks_core = "0.1.2"
tokio = { version = "1.0", features = ["full"] }
chrono = { version = "0.4", features = ["serde"] }

System Prerequisites

To build system keyring bindings (keyring) and OpenSSL dependencies on Linux, install the required development headers:

# Ubuntu / Debian
sudo apt install build-essential pkg-config libssl-dev libsecret-1-dev

# Fedora
sudo dnf install @development-tools openssl-devel libsecret-devel

# Arch Linux
sudo pacman -S base-devel openssl libsecret

🚀 Quickstart

1. Authenticate & Perform API Operations

obtain_authenticated_client() automatically retrieves saved credentials from the system keyring, or initiates a browser OAuth PKCE authorization loop if no valid token exists.

use gtasks_core::obtain_authenticated_client;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    // 1. Authenticate (Keyring lookup -> Browser PKCE fallback)
    let mut client = obtain_authenticated_client().await?;

    // 2. Fetch remote task lists
    let lists = client.get_task_lists().await?;
    println!("Found {} task lists:", lists.len());
    
    for list in &lists {
        println!(" - {} (ID: {})", list.title, list.id);
    }

    // 3. Create a new task list
    let task_list = client
        .create_task_list("Shopping List")
        .await?;
    println!("Created task list: {}", task_list.title);

    Ok(())
}

2. Offline-First SQLite Synchronization

Use Database for local persistence and sync_remote_to_db for bidirectional synchronization:

use gtasks_core::{obtain_authenticated_client, Database, sync_remote_to_db};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    let mut client = obtain_authenticated_client().await?;
    let mut db = Database::new("tasks_cache.db")?;

    // Perform bidirectional sync: Local dirty tasks -> Google API -> SQLite
    sync_remote_to_db(&mut client, &mut db).await?;

    // Query cached tasks offline
    let tasks = db.get_all_tasks()?;
    for task in tasks {
        let status = if task.is_completed { "✓" } else { " " };
        println!("[{}] {}", status, task.title.unwrap_or_default());
    }

    Ok(())
}

🏗️ Architecture Overview

               ┌──────────────────────────────────────────────┐
               │    Client App (TUI / GUI / CLI Script)       │
               └──────────────┬────────────────┬──────────────┘
                              │                │
            Local Queries &   │                │ Background Events
            Offline Writes    ▼                ▼
               ┌────────────────────┐    ┌────────────────────┐
               │  Database (SQLite) │    │    SyncManager     │
               └─────────▲──────────┘    └─────────┬──────────┘
                         │                         │
                         └──────────┬──────────────┘
                                    │ Network Sync
                                    ▼
               ┌──────────────────────────────────────────────┐
               │         GoogleTasksClient (REST API)         │
               └────────────────────┬─────────────────────────┘
                                    │ HTTPS (Bearer Auth)
                                    ▼
               ┌──────────────────────────────────────────────┐
               │              Google Tasks API                │
               └──────────────────────────────────────────────┘

The library is organized into specialized modules:

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

📄 License

Distributed under the MIT License. See LICENSE.md for details.