checkvist-api – Go-Client für die Checkvist API

checkvist-api ist eine typsichere, idiomatische Go-Bibliothek für den Zugriff auf die Checkvist API.

Was ist Checkvist?

Checkvist ist ein leistungsfähiger Outliner und Aufgabenmanager, der sich besonders für hierarchische Listen und komplexe Projekte eignet. Die Stärke liegt in der Tastatur-orientierten Bedienung und der Möglichkeit, Aufgaben beliebig tief zu verschachteln.

Warum diese Library?

Ich nutze Checkvist für meine persönliche Aufgabenverwaltung und wollte Tasks aus anderen Systemen synchronisieren oder automatisch erstellen können – zum Beispiel wiederkehrende Aufgaben oder Einträge aus Automatisierungsworkflows.

Installation

go get code.beautifulmachines.dev/jakoubek/checkvist-api

Authentifizierung

Die Library übernimmt die Authentifizierung automatisch – inklusive Token-Refresh:

client := checkvist.NewClient("your-email@example.com", "your-api-key")

Bei aktivierter Zwei-Faktor-Authentifizierung:

err := client.AuthenticateWith2FA(ctx, "123456")

Schnellstart

package main

import (
    "context"
    "fmt"
    "log"

    "code.beautifulmachines.dev/jakoubek/checkvist-api"
)

func main() {
    client := checkvist.NewClient("your-email@example.com", "your-api-key")
    ctx := context.Background()

    // Alle Checklisten auflisten
    checklists, err := client.Checklists().List(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, cl := range checklists {
        fmt.Printf("Checkliste: %s (%d Tasks)\n", cl.Name, cl.TaskCount)
    }

    // Neuen Task erstellen
    task, err := client.Tasks(checklists[0].ID).Create(ctx,
        checkvist.NewTask("Einkaufen gehen").
            WithDueDate(checkvist.DueTomorrow).
            WithPriority(1).
            WithTags("einkauf", "privat"),
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Task erstellt: %s (ID: %d)\n", task.Content, task.ID)
}

Checklisten verwalten

// Alle Checklisten auflisten
checklists, err := client.Checklists().List(ctx)

// Einzelne Checkliste abrufen
checklist, err := client.Checklists().Get(ctx, checklistID)

// Neue Checkliste erstellen
checklist, err := client.Checklists().Create(ctx, "Meine neue Liste")

// Checkliste umbenennen
checklist, err := client.Checklists().Update(ctx, checklistID, "Neuer Name")

Tasks verwalten

// Task mit Builder-Pattern erstellen
task, err := client.Tasks(checklistID).Create(ctx,
    checkvist.NewTask("Task-Inhalt").
        WithParent(parentID).       // Als Subtask erstellen
        WithDueDate(checkvist.DueAt(time.Now().AddDate(0, 0, 7))).
        WithPriority(1).            // 1 = höchste, 2 = hoch, 0 = normal
        WithTags("arbeit", "wichtig"),
)

// Task abschließen/wiedereröffnen
task, err := client.Tasks(checklistID).Close(ctx, taskID)
task, err := client.Tasks(checklistID).Reopen(ctx, taskID)

Fälligkeitsdaten

Die Library bietet praktische Helfer für Fälligkeitsdaten:

checkvist.DueToday              // Heute
checkvist.DueTomorrow           // Morgen
checkvist.DueInDays(5)          // In 5 Tagen
checkvist.DueAt(time.Time)      // Bestimmtes Datum
checkvist.DueString("friday")   // Smart Syntax

Notizen (Kommentare)

// Notizen eines Tasks auflisten
notes, err := client.Notes(checklistID, taskID).List(ctx)

// Notiz hinzufügen
note, err := client.Notes(checklistID, taskID).Create(ctx, "Mein Kommentar")

Fehlerbehandlung

Die Library bietet typisierte Fehler:

task, err := client.Tasks(checklistID).Get(ctx, taskID)
if err != nil {
    if errors.Is(err, checkvist.ErrNotFound) {
        fmt.Println("Task nicht gefunden")
    } else if errors.Is(err, checkvist.ErrUnauthorized) {
        fmt.Println("Ungültige Anmeldedaten")
    } else if errors.Is(err, checkvist.ErrRateLimited) {
        fmt.Println("Rate-Limit erreicht")
    }
}

Konfiguration

Der Client lässt sich anpassen:

client := checkvist.NewClient("email", "api-key",
    checkvist.WithTimeout(60 * time.Second),
    checkvist.WithRetryConfig(checkvist.RetryConfig{
        MaxRetries: 5,
        BaseDelay:  2 * time.Second,
    }),
)

Thread-Sicherheit

Der Client ist thread-safe und übernimmt automatisch die Token-Verwaltung.

Lizenz

MIT License – siehe LICENSE.