things3

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 28, 2025 License: Apache-2.0 Imports: 14 Imported by: 0

README

things3

Go CI codecov Go Reference Go Report Card License

Go library for Things 3 on macOS. Provides read-only database access and full URL Scheme support for creating and updating tasks.

Features

  • Read-only access to Things 3 SQLite database
  • Fluent query builder with type-safe filters
  • Full Things URL Scheme support
  • Create todos, projects, and batch operations via URL
  • Update existing items with authentication

Installation

go get github.com/moond4rk/things3

Note: Requires CGO enabled (uses go-sqlite3). macOS only.

Quick Start

Reading from Database
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/moond4rk/things3"
)

func main() {
    db, err := things3.NewDB()
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    ctx := context.Background()

    // Get today's tasks
    today, _ := db.Today(ctx)
    for _, task := range today {
        fmt.Printf("- %s\n", task.Title)
    }
}
Creating Tasks via URL Scheme
scheme := things3.NewScheme()

// Create a new todo
url, _ := scheme.Todo().
    Title("Buy groceries").
    Notes("Milk, eggs, bread").
    When(things3.WhenToday).
    Tags("shopping").
    Build()
// Output: things:///add?title=Buy+groceries&notes=Milk,+eggs,+bread&when=today&tags=shopping

Database API

Convenience Methods
db.Inbox(ctx)                    // Tasks in Inbox
db.Today(ctx)                    // Today's tasks
db.Upcoming(ctx)                 // Scheduled future tasks
db.Anytime(ctx)                  // Anytime tasks
db.Someday(ctx)                  // Someday tasks
db.Logbook(ctx)                  // Completed/canceled tasks
db.Trash(ctx)                    // Trashed tasks
db.Todos(ctx)                    // All incomplete to-dos
db.Projects(ctx)                 // All incomplete projects
db.Deadlines(ctx)                // Tasks with deadlines
db.Search(ctx, "query")          // Search tasks
db.CreatedWithin(ctx, Days(7))   // Tasks from last 7 days
Fluent Query Builder
// Type-safe status filtering
tasks, _ := db.Tasks().
    Type().Todo().
    Status().Incomplete().
    All(ctx)

// Date filtering
tasks, _ := db.Tasks().
    StartDate().Future().
    Deadline().OnOrBefore(time.Now().AddDate(0, 0, 7)).
    All(ctx)

// Filter by area, project, or tag
tasks, _ := db.Tasks().
    InArea("area-uuid").
    InTag("work").
    All(ctx)

// Get single task or count
task, _ := db.Tasks().WithUUID("task-uuid").First(ctx)
count, _ := db.Tasks().Status().Completed().Count(ctx)
Areas and Tags
// Get all areas with their tasks
areas, _ := db.Areas().IncludeItems(true).All(ctx)

// Get all tags
tags, _ := db.Tags().All(ctx)

URL Scheme API

Create Todo
scheme := things3.NewScheme()

url, _ := scheme.Todo().
    Title("Task title").
    Notes("Task notes").
    When(things3.WhenToday).              // or WhenTomorrow, WhenEvening, WhenAnytime, WhenSomeday
    WhenDate(2024, time.December, 25).    // specific date
    Deadline("2024-12-31").
    Tags("work", "urgent").
    ChecklistItems("Step 1", "Step 2").
    List("Project Name").                  // or ListID("project-uuid")
    Reveal(true).
    Build()
Create Project
url, _ := scheme.Project().
    Title("New Project").
    Notes("Project description").
    Area("Work").                          // or AreaID("area-uuid")
    Tags("important").
    Deadline("2024-12-31").
    Todos("Task 1", "Task 2", "Task 3").   // child todos
    Build()
Navigate to Views
scheme.Show().List(things3.ListToday).Build()    // things:///show?id=today
scheme.Show().List(things3.ListInbox).Build()    // things:///show?id=inbox
scheme.Show().ID("project-uuid").Build()          // things:///show?id=project-uuid
scheme.Search("urgent tasks")                     // things:///search?query=urgent+tasks
Update Existing Items (Requires Auth)
// Get auth token from database
token, _ := db.Token(ctx)
auth := scheme.WithToken(token)

// Update a todo
url, _ := auth.UpdateTodo("todo-uuid").
    Title("Updated title").
    Completed(true).
    AddTags("done").
    Build()

// Update a project
url, _ := auth.UpdateProject("project-uuid").
    Notes("Updated notes").
    Canceled(true).
    Build()
Batch Operations with JSON
// Create multiple items at once
url, _ := scheme.JSON().
    AddTodo(func(t *things3.JSONTodoBuilder) {
        t.Title("Task 1").Tags("work")
    }).
    AddTodo(func(t *things3.JSONTodoBuilder) {
        t.Title("Task 2").When(things3.WhenToday)
    }).
    AddProject(func(p *things3.JSONProjectBuilder) {
        p.Title("New Project").Notes("Description")
    }).
    Reveal(true).
    Build()

// Batch updates (requires auth)
url, _ := auth.JSON().
    UpdateTodo("uuid-1", func(t *things3.JSONTodoBuilder) {
        t.Completed(true)
    }).
    UpdateTodo("uuid-2", func(t *things3.JSONTodoBuilder) {
        t.Canceled(true)
    }).
    Build()

Configuration

// Use custom database path
db, _ := things3.NewDB(
    things3.WithDatabasePath("/path/to/main.sqlite"),
)

// Enable SQL logging for debugging
db, _ := things3.NewDB(
    things3.WithPrintSQL(true),
)
Database Discovery

The database path is resolved in order:

  1. Custom path via WithDatabasePath()
  2. THINGSDB environment variable
  3. Default: ~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/Things Database.thingsdatabase/main.sqlite

Types

// Task types
things3.TaskTypeTodo     // 0 - To-do item
things3.TaskTypeProject  // 1 - Project
things3.TaskTypeHeading  // 2 - Heading

// Status
things3.StatusIncomplete // 0
things3.StatusCanceled   // 2
things3.StatusCompleted  // 3

// Start bucket
things3.StartInbox    // 0
things3.StartAnytime  // 1
things3.StartSomeday  // 2

// When values for URL Scheme
things3.WhenToday
things3.WhenTomorrow
things3.WhenEvening
things3.WhenAnytime
things3.WhenSomeday

// List IDs for navigation
things3.ListInbox
things3.ListToday
things3.ListUpcoming
things3.ListAnytime
things3.ListSomeday
things3.ListLogbook
things3.ListTrash

References

License

Apache License 2.0

Documentation

Overview

Package things3 provides a Go library for Things 3 on macOS with read-only database access and full URL Scheme support for creating and updating tasks.

Features

This package offers two main capabilities:

  • Read-only access to the Things 3 SQLite database for querying tasks, projects, areas, and tags
  • Full Things URL Scheme support for creating, updating, and navigating to items

Database Access

Create a database connection and query tasks: 

db, err := things3.NewDB()
if err != nil {
    log.Fatal(err)
}
defer db.Close()

// Convenience methods
inbox, _ := db.Inbox(ctx)
today, _ := db.Today(ctx)
todos, _ := db.Todos(ctx)

Fluent Query Builder

For complex queries, use the type-safe fluent query builder: 

tasks, _ := db.Tasks().
    Type().Todo().
    Status().Incomplete().
    StartDate().Future().
    All(ctx)

URL Scheme

Create Things URLs for automation and integration: 

scheme := things3.NewScheme()

// Create a new todo
url, _ := scheme.Todo().
    Title("Buy groceries").
    When(things3.WhenToday).
    Tags("shopping").
    Build()

// Update existing items (requires auth token)
token, _ := db.Token(ctx)
auth := scheme.WithToken(token)
url, _ := auth.UpdateTodo("uuid").Completed(true).Build()

Configuration

Configure the database with functional options: 

db, _ := things3.NewDB(things3.WithDatabasePath("/path/to/main.sqlite"))
db, _ := things3.NewDB(things3.WithPrintSQL(true))

Database Discovery

The database path is discovered in the following order:

  1. Custom path provided via WithDatabasePath option
  2. THINGSDB environment variable
  3. Auto-discovery of default Things 3 database location

Type System

The package uses integer-based enums that map directly to database values:

  • TaskType: TaskTypeTodo (0), TaskTypeProject (1), TaskTypeHeading (2)
  • Status: StatusIncomplete (0), StatusCanceled (2), StatusCompleted (3)
  • StartBucket: StartInbox (0), StartAnytime (1), StartSomeday (2)

References

For the official Things URL Scheme documentation, see: https://culturedcode.com/things/support/articles/2803573/

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrDatabaseNotFound is returned when the Things database cannot be located.
	ErrDatabaseNotFound = errors.New("things3: database not found")
	// ErrDatabaseVersionTooOld is returned when the database version is not supported.
	ErrDatabaseVersionTooOld = errors.New("things3: database version too old (requires things3 version > 21)")
)

Database Errors

View Source 
var (
	// ErrTaskNotFound is returned when a task with the specified UUID does not exist.
	ErrTaskNotFound = errors.New("things3: task not found")
	// ErrAreaNotFound is returned when an area with the specified UUID does not exist.
	ErrAreaNotFound = errors.New("things3: area not found")
	// ErrTagNotFound is returned when a tag with the specified title does not exist.
	ErrTagNotFound = errors.New("things3: tag not found")
	// ErrInvalidParameter is returned when an invalid parameter value is provided.
	ErrInvalidParameter = errors.New("things3: invalid parameter")
)

Query Errors

View Source 
var (
	// ErrAuthTokenNotFound is returned when the URL scheme auth token cannot be read.
	ErrAuthTokenNotFound = errors.New("things3: auth token not found")
	// ErrEmptyToken is returned when an empty token is provided to WithToken.
	ErrEmptyToken = errors.New("things3: empty token provided to WithToken")
	// ErrIDRequired is returned when id is missing for an update operation.
	ErrIDRequired = errors.New("things3: id required for update operation")
	// ErrTitleTooLong is returned when title exceeds 4,000 character limit.
	ErrTitleTooLong = errors.New("things3: title exceeds 4,000 character limit")
	// ErrNotesTooLong is returned when notes exceed 10,000 character limit.
	ErrNotesTooLong = errors.New("things3: notes exceed 10,000 character limit")
	// ErrTooManyChecklistItems is returned when checklist exceeds 100 item limit.
	ErrTooManyChecklistItems = errors.New("things3: checklist exceeds 100 item limit")
	// ErrNoJSONItems is returned when building a JSON URL with no items.
	ErrNoJSONItems = errors.New("things3: no items provided for JSON operation")
	// ErrInvalidReminderTime is returned when reminder hour or minute is out of range.
	ErrInvalidReminderTime = errors.New("things3: invalid reminder time (hour must be 0-23, minute must be 0-59)")
)

URL Scheme Errors

Functions

func Headings added in v0.2.0 

func Headings(headings ...string) string

Headings creates heading entries for a project's items. Used within JSONProjectBuilder.Todos to organize to-dos under headings.

Types

type Area 

type Area struct {
	UUID  string `json:"uuid"`
	Type  string `json:"type"` // Always "area"
	Title string `json:"title"`

	// Nested items (populated when include_items=true)
	Tags  []string `json:"tags,omitempty"`
	Items []Task   `json:"items,omitempty"`
}

Area represents an area in Things 3.

type AreaQuery 

type AreaQuery struct {
	// contains filtered or unexported fields
}

AreaQuery provides a fluent interface for building area queries.

func (*AreaQuery) All 

func (q *AreaQuery) All(ctx context.Context) ([]Area, error)

All executes the query and returns all matching areas.

func (*AreaQuery) Count 

func (q *AreaQuery) Count(ctx context.Context) (int, error)

Count executes the query and returns the count of matching areas.

func (*AreaQuery) First 

func (q *AreaQuery) First(ctx context.Context) (*Area, error)

First executes the query and returns the first matching area.

func (*AreaQuery) InTag added in v0.2.0 

func (q *AreaQuery) InTag(tag any) *AreaQuery

InTag filters areas by tag.

func (*AreaQuery) IncludeItems 

func (q *AreaQuery) IncludeItems(include bool) *AreaQuery

IncludeItems includes tasks in each area.

func (*AreaQuery) Visible added in v0.2.1 

func (q *AreaQuery) Visible(visible bool) *AreaQuery

Visible filters areas by visibility status. Pass true to include only visible areas. Pass false to include only hidden areas.

func (*AreaQuery) WithTitle added in v0.2.1 

func (q *AreaQuery) WithTitle(title string) *AreaQuery

WithTitle filters areas by title.

func (*AreaQuery) WithUUID 

func (q *AreaQuery) WithUUID(uuid string) *AreaQuery

WithUUID filters areas by UUID.

type AuthJSONBuilder added in v0.2.0 

type AuthJSONBuilder struct {
	// contains filtered or unexported fields
}

AuthJSONBuilder builds URLs for batch operations including updates via the json command. Requires authentication token for update operations.

func (*AuthJSONBuilder) AddProject added in v0.2.0 

func (b *AuthJSONBuilder) AddProject(configure func(*JSONProjectBuilder)) *AuthJSONBuilder

AddProject adds a project creation to the batch.

func (*AuthJSONBuilder) AddTodo added in v0.2.0 

func (b *AuthJSONBuilder) AddTodo(configure func(*JSONTodoBuilder)) *AuthJSONBuilder

AddTodo adds a to-do creation to the batch.

func (*AuthJSONBuilder) Build added in v0.2.0 

func (b *AuthJSONBuilder) Build() (string, error)

Build returns the Things URL for the JSON batch operation.

func (*AuthJSONBuilder) Execute added in v0.3.0 

func (b *AuthJSONBuilder) Execute(ctx context.Context) error

Execute builds and executes the JSON batch URL. Returns an error if the URL cannot be built or executed.

func (*AuthJSONBuilder) Reveal added in v0.2.0 

func (b *AuthJSONBuilder) Reveal(reveal bool) *AuthJSONBuilder

Reveal navigates to the first item after processing.

func (*AuthJSONBuilder) UpdateProject added in v0.2.0 

func (b *AuthJSONBuilder) UpdateProject(id string, configure func(*JSONProjectBuilder)) *AuthJSONBuilder

UpdateProject adds a project update to the batch.

func (*AuthJSONBuilder) UpdateTodo added in v0.2.0 

func (b *AuthJSONBuilder) UpdateTodo(id string, configure func(*JSONTodoBuilder)) *AuthJSONBuilder

UpdateTodo adds a to-do update to the batch.

type AuthScheme added in v0.2.0 

type AuthScheme struct {
	// contains filtered or unexported fields
}

AuthScheme provides URL building for authenticated operations. Obtained via Scheme.WithToken(token).

AuthScheme exposes update methods that require authentication:

  • UpdateTodo(id) - modify an existing to-do
  • UpdateProject(id) - modify an existing project
  • JSON() - batch operations including updates

func (*AuthScheme) JSON added in v0.2.0 

func (a *AuthScheme) JSON() *AuthJSONBuilder

JSON returns an AuthJSONBuilder for batch operations including updates.

func (*AuthScheme) UpdateProject added in v0.2.0 

func (a *AuthScheme) UpdateProject(id string) *UpdateProjectBuilder

UpdateProject returns an UpdateProjectBuilder for modifying an existing project.

func (*AuthScheme) UpdateTodo added in v0.2.0 

func (a *AuthScheme) UpdateTodo(id string) *UpdateTodoBuilder

UpdateTodo returns an UpdateTodoBuilder for modifying an existing to-do.

type ChecklistItem 

type ChecklistItem struct {
	UUID   string `json:"uuid"`
	Type   string `json:"type"` // Always "checklist-item"
	Title  string `json:"title"`
	Status string `json:"status"` // "incomplete", "completed", or "canceled"
	// StopDate: completion date.
	//   Database: "2024-01-15" (date only, format "YYYY-MM-DD")
	//   Parsed:   time.Time with zero time component
	StopDate *time.Time `json:"stop_date,omitempty"`
	// Created: item creation timestamp.
	//   Database: "2024-01-15 10:30:45" (datetime, format "YYYY-MM-DD HH:MM:SS")
	//   Parsed:   time.Time with full date and time
	Created time.Time `json:"created"`
	// Modified: last modification timestamp.
	//   Database: "2024-01-15 10:30:45" (datetime, format "YYYY-MM-DD HH:MM:SS")
	//   Parsed:   time.Time with full date and time
	Modified time.Time `json:"modified"`
}

ChecklistItem represents a checklist item within a to-do.

func (*ChecklistItem) IsCanceled 

func (c *ChecklistItem) IsCanceled() bool

IsCanceled returns true if the checklist item is canceled.

func (*ChecklistItem) IsCompleted 

func (c *ChecklistItem) IsCompleted() bool

IsCompleted returns true if the checklist item is completed.

func (*ChecklistItem) IsIncomplete 

func (c *ChecklistItem) IsIncomplete() bool

IsIncomplete returns true if the checklist item is incomplete.

type Command added in v0.2.0 

type Command string

Command represents Things URL scheme commands. 

const (
	// CommandShow opens and shows an item.
	CommandShow Command = "show"
	// CommandAdd creates a new to-do.
	CommandAdd Command = "add"
	// CommandAddProject creates a new project.
	CommandAddProject Command = "add-project"
	// CommandUpdate updates an existing item (requires auth token).
	CommandUpdate Command = "update"
	// CommandUpdateProject updates an existing project (requires auth token).
	CommandUpdateProject Command = "update-project"
	// CommandSearch performs a search.
	CommandSearch Command = "search"
	// CommandVersion returns Things version information.
	CommandVersion Command = "version"
	// CommandJSON enables advanced JSON-based operations.
	CommandJSON Command = "json"
)

func (Command) String added in v0.2.0 

func (c Command) String() string

String returns the string representation of the Command.

type DB added in v0.2.0 

type DB struct {
	// contains filtered or unexported fields
}

DB provides read-only access to the Things 3 database.

func NewDB added in v0.2.0 

func NewDB(opts ...DBOption) (*DB, error)

NewDB creates a new Things 3 database connection. Options can be provided to configure the database behavior.

func (*DB) Anytime added in v0.2.0 

func (d *DB) Anytime(ctx context.Context) ([]Task, error)

Anytime returns tasks in the Anytime list.

func (*DB) Areas added in v0.2.0 

func (d *DB) Areas() *AreaQuery

Areas creates a new AreaQuery for querying areas.

func (*DB) Canceled added in v0.2.0 

func (d *DB) Canceled(ctx context.Context) ([]Task, error)

Canceled returns canceled tasks.

func (*DB) ChecklistItems added in v0.2.0 

func (d *DB) ChecklistItems(ctx context.Context, todoUUID string) ([]ChecklistItem, error)

ChecklistItems returns the checklist items for a to-do.

func (*DB) Close added in v0.2.0 

func (d *DB) Close() error

Close closes the database connection.

func (*DB) Completed added in v0.2.0 

func (d *DB) Completed(ctx context.Context) ([]Task, error)

Completed returns completed tasks.

func (*DB) CreatedWithin added in v0.2.0 

func (d *DB) CreatedWithin(ctx context.Context, duration Duration) ([]Task, error)

CreatedWithin returns tasks created within the specified duration. Example: db.CreatedWithin(ctx, Days(7))

func (*DB) Deadlines added in v0.2.0 

func (d *DB) Deadlines(ctx context.Context) ([]Task, error)

Deadlines returns tasks with deadlines, sorted by deadline.

func (*DB) Filepath added in v0.2.0 

func (d *DB) Filepath() string

Filepath returns the path to the Things database file.

func (*DB) Get added in v0.2.0 

func (d *DB) Get(ctx context.Context, uuid string) (any, error)

Get retrieves an object by UUID. Returns a Task, Area, or Tag depending on what is found. Returns nil if not found.

func (*DB) Inbox added in v0.2.0 

func (d *DB) Inbox(ctx context.Context) ([]Task, error)

Inbox returns all tasks in the Inbox.

func (*DB) Logbook added in v0.2.0 

func (d *DB) Logbook(ctx context.Context) ([]Task, error)

Logbook returns completed and canceled tasks, sorted by stop date.

func (*DB) Projects added in v0.2.0 

func (d *DB) Projects(ctx context.Context) ([]Task, error)

Projects returns all incomplete projects.

func (*DB) Search added in v0.2.0 

func (d *DB) Search(ctx context.Context, query string) ([]Task, error)

Search searches for tasks matching the query. Searches in task title, notes, and area title.

func (*DB) Someday added in v0.2.0 

func (d *DB) Someday(ctx context.Context) ([]Task, error)

Someday returns tasks in the Someday list (without a start date).

func (*DB) Tags added in v0.2.0 

func (d *DB) Tags() *TagQuery

Tags creates a new TagQuery for querying tags.

func (*DB) Tasks added in v0.2.0 

func (d *DB) Tasks() *TaskQuery

Tasks creates a new TaskQuery for querying tasks.

func (*DB) Today added in v0.2.0 

func (d *DB) Today(ctx context.Context) ([]Task, error)

Today returns tasks that would appear in Today view. This includes: - Tasks with a start date set to today or earlier and in Anytime - Scheduled tasks from Someday with past start dates (yellow dot tasks) - Overdue tasks with deadlines that haven't been suppressed

func (*DB) Todos added in v0.2.0 

func (d *DB) Todos(ctx context.Context) ([]Task, error)

Todos returns all incomplete to-do items.

func (*DB) Token added in v0.2.0 

func (d *DB) Token(ctx context.Context) (string, error)

Token returns the Things URL scheme authentication token.

func (*DB) Trash added in v0.2.0 

func (d *DB) Trash(ctx context.Context) ([]Task, error)

Trash returns trashed tasks.

func (*DB) Upcoming added in v0.2.0 

func (d *DB) Upcoming(ctx context.Context) ([]Task, error)

Upcoming returns tasks scheduled for future dates.

type DBOption added in v0.2.0 

type DBOption func(*dbOptions)

DBOption is a functional option for configuring the DB.

func WithDBPath added in v0.2.0 

func WithDBPath(path string) DBOption

WithDBPath sets a custom path to the Things database. If not set, the database path is discovered automatically.

func WithPrintSQL 

func WithPrintSQL(enabled bool) DBOption

WithPrintSQL enables SQL query logging to stdout. Useful for debugging and understanding the queries being executed.

type DateFilter added in v0.2.0 

type DateFilter struct {
	// contains filtered or unexported fields
}

DateFilter provides type-safe date filtering for TaskQuery. It is used for startDate, stopDate, and deadline fields. Use the terminal methods to set the filter and return to the parent TaskQuery.

func (*DateFilter) After added in v0.2.0 

func (f *DateFilter) After(date time.Time) *TaskQuery

After filters for dates after the given date (exclusive).

func (*DateFilter) Before added in v0.2.0 

func (f *DateFilter) Before(date time.Time) *TaskQuery

Before filters for dates before the given date (exclusive).

func (*DateFilter) Exists added in v0.2.0 

func (f *DateFilter) Exists(has bool) *TaskQuery

Exists filters by whether the date exists (is not null). Pass true to include only items with this date set. Pass false to include only items without this date set.

func (*DateFilter) Future added in v0.2.0 

func (f *DateFilter) Future() *TaskQuery

Future filters for dates in the future (after today).

func (*DateFilter) On added in v0.2.0 

func (f *DateFilter) On(date time.Time) *TaskQuery

On filters for a specific date (equals).

func (*DateFilter) OnOrAfter added in v0.2.0 

func (f *DateFilter) OnOrAfter(date time.Time) *TaskQuery

OnOrAfter filters for dates on or after the given date (inclusive).

func (*DateFilter) OnOrBefore added in v0.2.0 

func (f *DateFilter) OnOrBefore(date time.Time) *TaskQuery

OnOrBefore filters for dates on or before the given date (inclusive).

func (*DateFilter) Past added in v0.2.0 

func (f *DateFilter) Past() *TaskQuery

Past filters for dates in the past (today or earlier).

type Duration added in v0.2.0 

type Duration struct {
	// contains filtered or unexported fields
}

Duration represents a time duration for filtering tasks by creation date. Use the helper functions Days(), Weeks(), Months(), Years() to create durations.

func Days added in v0.2.0 

func Days(n int) Duration

Days creates a Duration of n days.

func Months added in v0.2.0 

func Months(n int) Duration

Months creates a Duration of n months.

func Weeks added in v0.2.0 

func Weeks(n int) Duration

Weeks creates a Duration of n weeks.

func Years added in v0.2.0 

func Years(n int) Duration

Years creates a Duration of n years.

func (Duration) IsZero added in v0.2.0 

func (d Duration) IsZero() bool

IsZero returns true if the duration is zero.

type JSONBuilder added in v0.2.0 

type JSONBuilder struct {
	// contains filtered or unexported fields
}

JSONBuilder builds URLs for batch create operations via the json command. Does not support update operations; use AuthJSONBuilder for updates.

func (*JSONBuilder) AddProject added in v0.2.0 

func (b *JSONBuilder) AddProject(configure func(*JSONProjectBuilder)) *JSONBuilder

AddProject adds a project creation to the batch.

func (*JSONBuilder) AddTodo added in v0.2.0 

func (b *JSONBuilder) AddTodo(configure func(*JSONTodoBuilder)) *JSONBuilder

AddTodo adds a to-do creation to the batch.

func (*JSONBuilder) Build added in v0.2.0 

func (b *JSONBuilder) Build() (string, error)

Build returns the Things URL for the JSON batch operation.

func (*JSONBuilder) Execute added in v0.3.0 

func (b *JSONBuilder) Execute(ctx context.Context) error

Execute builds and executes the JSON batch URL. Returns an error if the URL cannot be built or executed.

func (*JSONBuilder) Reveal added in v0.2.0 

func (b *JSONBuilder) Reveal(reveal bool) *JSONBuilder

Reveal navigates to the first created item after processing.

type JSONItem added in v0.2.0 

type JSONItem struct {
	Type       JSONItemType   `json:"type"`
	Operation  JSONOperation  `json:"operation,omitempty"`
	ID         string         `json:"id,omitempty"`
	Attributes map[string]any `json:"attributes,omitempty"`
}

JSONItem represents a single item in a JSON batch operation.

type JSONItemType added in v0.2.0 

type JSONItemType string

JSONItemType represents the type of item in a JSON operation. 

const (
	// JSONItemTypeTodo represents a to-do item.
	JSONItemTypeTodo JSONItemType = "to-do"
	// JSONItemTypeProject represents a project item.
	JSONItemTypeProject JSONItemType = "project"
)

type JSONOperation added in v0.2.0 

type JSONOperation string

JSONOperation represents the operation type for a JSON item. 

const (
	// JSONOperationCreate creates a new item.
	JSONOperationCreate JSONOperation = "create"
	// JSONOperationUpdate updates an existing item.
	JSONOperationUpdate JSONOperation = "update"
)

type JSONProjectBuilder added in v0.2.0 

type JSONProjectBuilder struct {
	// contains filtered or unexported fields
}

JSONProjectBuilder builds a project entry for JSON batch operations. Unlike ProjectBuilder which generates a complete URL, JSONProjectBuilder creates a JSON object that becomes part of a JSONBuilder or AuthJSONBuilder batch.

func NewProject added in v0.2.0 

func NewProject() *JSONProjectBuilder

NewProject creates a new JSONProjectBuilder for use with JSONBuilder.AddProject. This is a convenience function for inline configuration.

func (*JSONProjectBuilder) AddTags added in v0.2.0 

func (p *JSONProjectBuilder) AddTags(tags ...string) *JSONProjectBuilder

AddTags adds tags without replacing existing ones (update only).

func (*JSONProjectBuilder) AppendNotes added in v0.2.0 

func (p *JSONProjectBuilder) AppendNotes(notes string) *JSONProjectBuilder

AppendNotes appends text to existing notes (update only).

func (*JSONProjectBuilder) Area added in v0.2.0 

func (p *JSONProjectBuilder) Area(name string) *JSONProjectBuilder

Area sets the parent area by name.

func (*JSONProjectBuilder) AreaID added in v0.2.0 

func (p *JSONProjectBuilder) AreaID(id string) *JSONProjectBuilder

AreaID sets the parent area by UUID.

func (*JSONProjectBuilder) Canceled added in v0.2.0 

func (p *JSONProjectBuilder) Canceled(canceled bool) *JSONProjectBuilder

Canceled sets the canceled status.

func (*JSONProjectBuilder) Completed added in v0.2.0 

func (p *JSONProjectBuilder) Completed(completed bool) *JSONProjectBuilder

Completed sets the completion status.

func (*JSONProjectBuilder) CompletionDate added in v0.2.0 

func (p *JSONProjectBuilder) CompletionDate(date time.Time) *JSONProjectBuilder

CompletionDate sets the completion timestamp.

func (*JSONProjectBuilder) CreationDate added in v0.2.0 

func (p *JSONProjectBuilder) CreationDate(date time.Time) *JSONProjectBuilder

CreationDate sets the creation timestamp.

func (*JSONProjectBuilder) Deadline added in v0.2.0 

func (p *JSONProjectBuilder) Deadline(date string) *JSONProjectBuilder

Deadline sets the deadline date.

func (*JSONProjectBuilder) Notes added in v0.2.0 

func (p *JSONProjectBuilder) Notes(notes string) *JSONProjectBuilder

Notes sets the project notes.

func (*JSONProjectBuilder) PrependNotes added in v0.2.0 

func (p *JSONProjectBuilder) PrependNotes(notes string) *JSONProjectBuilder

PrependNotes prepends text to existing notes (update only).

func (*JSONProjectBuilder) Tags added in v0.2.0 

func (p *JSONProjectBuilder) Tags(tags ...string) *JSONProjectBuilder

Tags sets the tags for the project.

func (*JSONProjectBuilder) Title added in v0.2.0 

func (p *JSONProjectBuilder) Title(title string) *JSONProjectBuilder

Title sets the project title.

func (*JSONProjectBuilder) Todos added in v0.2.0 

func (p *JSONProjectBuilder) Todos(items ...*JSONTodoBuilder) *JSONProjectBuilder

Todos sets the child to-do items.

func (*JSONProjectBuilder) When added in v0.2.0 

func (p *JSONProjectBuilder) When(when When) *JSONProjectBuilder

When sets the scheduling date.

func (*JSONProjectBuilder) WhenDate added in v0.2.0 

func (p *JSONProjectBuilder) WhenDate(year int, month time.Month, day int) *JSONProjectBuilder

WhenDate sets a specific date for scheduling.

type JSONTodoBuilder added in v0.2.0 

type JSONTodoBuilder struct {
	// contains filtered or unexported fields
}

JSONTodoBuilder builds a to-do entry for JSON batch operations. Unlike TodoBuilder which generates a complete URL, JSONTodoBuilder creates a JSON object that becomes part of a JSONBuilder or AuthJSONBuilder batch.

Example: 

Scheme.JSON().
    AddTodo(func(b *JSONTodoBuilder) {
        b.Title("Buy milk").Tags("shopping")
    }).
    Build()

func NewTodo added in v0.2.0 

func NewTodo() *JSONTodoBuilder

NewTodo creates a new JSONTodoBuilder for use with JSONBuilder.AddTodo. This is a convenience function for inline configuration.

func (*JSONTodoBuilder) AddTags added in v0.2.0 

func (t *JSONTodoBuilder) AddTags(tags ...string) *JSONTodoBuilder

AddTags adds tags without replacing existing ones (update only).

func (*JSONTodoBuilder) AppendNotes added in v0.2.0 

func (t *JSONTodoBuilder) AppendNotes(notes string) *JSONTodoBuilder

AppendNotes appends text to existing notes (update only).

func (*JSONTodoBuilder) Canceled added in v0.2.0 

func (t *JSONTodoBuilder) Canceled(canceled bool) *JSONTodoBuilder

Canceled sets the canceled status.

func (*JSONTodoBuilder) ChecklistItems added in v0.2.0 

func (t *JSONTodoBuilder) ChecklistItems(items ...string) *JSONTodoBuilder

ChecklistItems sets the checklist items.

func (*JSONTodoBuilder) Completed added in v0.2.0 

func (t *JSONTodoBuilder) Completed(completed bool) *JSONTodoBuilder

Completed sets the completion status.

func (*JSONTodoBuilder) CompletionDate added in v0.2.0 

func (t *JSONTodoBuilder) CompletionDate(date time.Time) *JSONTodoBuilder

CompletionDate sets the completion timestamp.

func (*JSONTodoBuilder) CreationDate added in v0.2.0 

func (t *JSONTodoBuilder) CreationDate(date time.Time) *JSONTodoBuilder

CreationDate sets the creation timestamp.

func (*JSONTodoBuilder) Deadline added in v0.2.0 

func (t *JSONTodoBuilder) Deadline(date string) *JSONTodoBuilder

Deadline sets the deadline date.

func (*JSONTodoBuilder) Heading added in v0.2.0 

func (t *JSONTodoBuilder) Heading(name string) *JSONTodoBuilder

Heading sets the target heading within a project by name.

func (*JSONTodoBuilder) List added in v0.2.0 

func (t *JSONTodoBuilder) List(name string) *JSONTodoBuilder

List sets the target project or area by name.

func (*JSONTodoBuilder) ListID added in v0.2.0 

func (t *JSONTodoBuilder) ListID(id string) *JSONTodoBuilder

ListID sets the target project or area by UUID.

func (*JSONTodoBuilder) Notes added in v0.2.0 

func (t *JSONTodoBuilder) Notes(notes string) *JSONTodoBuilder

Notes sets the to-do notes.

func (*JSONTodoBuilder) PrependNotes added in v0.2.0 

func (t *JSONTodoBuilder) PrependNotes(notes string) *JSONTodoBuilder

PrependNotes prepends text to existing notes (update only).

func (*JSONTodoBuilder) Tags added in v0.2.0 

func (t *JSONTodoBuilder) Tags(tags ...string) *JSONTodoBuilder

Tags sets the tags for the to-do.

func (*JSONTodoBuilder) Title added in v0.2.0 

func (t *JSONTodoBuilder) Title(title string) *JSONTodoBuilder

Title sets the to-do title.

func (*JSONTodoBuilder) When added in v0.2.0 

func (t *JSONTodoBuilder) When(when When) *JSONTodoBuilder

When sets the scheduling date.

func (*JSONTodoBuilder) WhenDate added in v0.2.0 

func (t *JSONTodoBuilder) WhenDate(year int, month time.Month, day int) *JSONTodoBuilder

WhenDate sets a specific date for scheduling.

type ListID added in v0.2.0 

type ListID string

ListID represents built-in Things list identifiers for the show command. 

const (
	// ListInbox is the Inbox list.
	ListInbox ListID = "inbox"
	// ListToday is the Today list.
	ListToday ListID = "today"
	// ListAnytime is the Anytime list.
	ListAnytime ListID = "anytime"
	// ListUpcoming is the Upcoming list.
	ListUpcoming ListID = "upcoming"
	// ListSomeday is the Someday list.
	ListSomeday ListID = "someday"
	// ListLogbook is the Logbook list.
	ListLogbook ListID = "logbook"
	// ListTomorrow is the Tomorrow list.
	ListTomorrow ListID = "tomorrow"
	// ListDeadlines is the Deadlines list.
	ListDeadlines ListID = "deadlines"
	// ListRepeating is the Repeating list.
	ListRepeating ListID = "repeating"
	// ListAllProjects is the All Projects list.
	ListAllProjects ListID = "all-projects"
	// ListLoggedProjects is the Logged Projects list.
	ListLoggedProjects ListID = "logged-projects"
)

func (ListID) String added in v0.2.0 

func (l ListID) String() string

String returns the string representation of the ListID.

type ProjectBuilder added in v0.2.0 

type ProjectBuilder struct {
	// contains filtered or unexported fields
}

ProjectBuilder builds URLs for creating new projects via the add-project command.

func (*ProjectBuilder) Area added in v0.2.0 

func (b *ProjectBuilder) Area(name string) *ProjectBuilder

Area sets the parent area by name.

func (*ProjectBuilder) AreaID added in v0.2.0 

func (b *ProjectBuilder) AreaID(id string) *ProjectBuilder

AreaID sets the parent area by UUID.

func (*ProjectBuilder) Build added in v0.2.0 

func (b *ProjectBuilder) Build() (string, error)

Build returns the Things URL for creating the project.

func (*ProjectBuilder) Canceled added in v0.2.0 

func (b *ProjectBuilder) Canceled(canceled bool) *ProjectBuilder

Canceled sets the canceled status.

func (*ProjectBuilder) Completed added in v0.2.0 

func (b *ProjectBuilder) Completed(completed bool) *ProjectBuilder

Completed sets the completion status.

func (*ProjectBuilder) CompletionDate added in v0.2.0 

func (b *ProjectBuilder) CompletionDate(date time.Time) *ProjectBuilder

CompletionDate sets the completion timestamp.

func (*ProjectBuilder) CreationDate added in v0.2.0 

func (b *ProjectBuilder) CreationDate(date time.Time) *ProjectBuilder

CreationDate sets the creation timestamp.

func (*ProjectBuilder) Deadline added in v0.2.0 

func (b *ProjectBuilder) Deadline(date string) *ProjectBuilder

Deadline sets the deadline date in yyyy-mm-dd format.

func (*ProjectBuilder) Execute added in v0.3.0 

func (b *ProjectBuilder) Execute(ctx context.Context) error

Execute builds and executes the add-project URL. Returns an error if the URL cannot be built or executed.

func (*ProjectBuilder) Notes added in v0.2.0 

func (b *ProjectBuilder) Notes(notes string) *ProjectBuilder

Notes sets the project notes/description.

func (*ProjectBuilder) Reminder added in v0.3.0 

func (b *ProjectBuilder) Reminder(hour, minute int) *ProjectBuilder

Reminder sets a reminder time for the project. The reminder is combined with the scheduling date (When/WhenDate). If no scheduling date is set, defaults to "today". Hour must be 0-23, minute must be 0-59.

func (*ProjectBuilder) Reveal added in v0.2.0 

func (b *ProjectBuilder) Reveal(reveal bool) *ProjectBuilder

Reveal navigates to the newly created project.

func (*ProjectBuilder) Tags added in v0.2.0 

func (b *ProjectBuilder) Tags(tags ...string) *ProjectBuilder

Tags sets the tags for the project.

func (*ProjectBuilder) Title added in v0.2.0 

func (b *ProjectBuilder) Title(title string) *ProjectBuilder

Title sets the project title.

func (*ProjectBuilder) Todos added in v0.2.0 

func (b *ProjectBuilder) Todos(titles ...string) *ProjectBuilder

Todos sets the child to-do titles.

func (*ProjectBuilder) When added in v0.2.0 

func (b *ProjectBuilder) When(when When) *ProjectBuilder

When sets the scheduling date.

func (*ProjectBuilder) WhenDate added in v0.2.0 

func (b *ProjectBuilder) WhenDate(year int, month time.Month, day int) *ProjectBuilder

WhenDate sets a specific date for scheduling.

type Scheme added in v0.2.0 

type Scheme struct {
	// contains filtered or unexported fields
}

Scheme provides URL building and execution for Things URL Scheme.

Use NewScheme() to create a new instance: 

scheme := things3.NewScheme()
url, _ := scheme.Todo().Title("Buy groceries").Build()

For executing URL scheme operations: 

// Show a task (runs in background by default)
scheme.Show(ctx, "uuid")

// Show a task in foreground
things3.NewScheme(things3.WithForeground()).Show(ctx, "uuid")

For operations requiring authentication (update operations), use WithToken() to get an AuthScheme: 

token, _ := db.Token(ctx)
auth := scheme.WithToken(token)
auth.UpdateTodo("uuid").Completed(true).Execute(ctx)

func NewScheme added in v0.2.0 

func NewScheme(opts ...SchemeOption) *Scheme

NewScheme creates a new URL Scheme builder. Options can be provided to configure execution behavior.

func (*Scheme) JSON added in v0.2.0 

func (s *Scheme) JSON() *JSONBuilder

JSON returns a JSONBuilder for batch create operations. For operations including updates, use AuthScheme.JSON() instead.

func (*Scheme) Project added in v0.2.0 

func (s *Scheme) Project() *ProjectBuilder

Project returns a ProjectBuilder for creating a new project.

func (*Scheme) Search added in v0.2.0 

func (s *Scheme) Search(ctx context.Context, query string) error

Search opens Things and performs a search for the given query. By default, runs in background without stealing focus. Use WithForeground() option to bring Things to foreground.

func (*Scheme) SearchURL added in v0.3.0 

func (s *Scheme) SearchURL(query string) string

SearchURL returns a URL to search for the given query in Things. For direct execution, use Search(ctx, query) instead.

func (*Scheme) Show added in v0.2.0 

func (s *Scheme) Show(ctx context.Context, uuid string) error

Show opens Things and shows the item with the given UUID. By default, runs in background without stealing focus. Use WithForeground() option to bring Things to foreground.

func (*Scheme) ShowBuilder added in v0.3.0 

func (s *Scheme) ShowBuilder() *ShowBuilder

ShowBuilder returns a ShowBuilder for navigating to items or lists. For direct execution, use Show(ctx, uuid) instead.

func (*Scheme) Todo added in v0.2.0 

func (s *Scheme) Todo() *TodoBuilder

Todo returns a TodoBuilder for creating a new to-do.

func (*Scheme) Version added in v0.2.0 

func (s *Scheme) Version() string

Version returns a URL to get Things version information.

func (*Scheme) WithToken added in v0.2.0 

func (s *Scheme) WithToken(token string) *AuthScheme

WithToken returns an AuthScheme for authenticated operations. The token is required for update operations (UpdateTodo, UpdateProject).

Get the token from the database: 

db, _ := things3.NewDB()
token, _ := db.Token(ctx)
auth := scheme.WithToken(token)
auth.UpdateTodo("uuid").Completed(true).Execute(ctx)

type SchemeOption added in v0.3.0 

type SchemeOption func(*Scheme)

SchemeOption configures Scheme behavior.

func WithForeground added in v0.3.0 

func WithForeground() SchemeOption

WithForeground configures the Scheme to bring Things to foreground when executing URL scheme operations. By default, operations run in background without stealing focus.

type ShowBuilder added in v0.2.0 

type ShowBuilder struct {
	// contains filtered or unexported fields
}

ShowBuilder builds URLs for navigating to items or lists via the show command.

func (*ShowBuilder) Build added in v0.2.0 

func (b *ShowBuilder) Build() string

Build returns the Things URL for the show command.

func (*ShowBuilder) Execute added in v0.3.0 

func (b *ShowBuilder) Execute(ctx context.Context) error

Execute builds and executes the show URL.

func (*ShowBuilder) Filter added in v0.2.0 

func (b *ShowBuilder) Filter(tags ...string) *ShowBuilder

Filter filters the displayed items by tags.

func (*ShowBuilder) ID added in v0.2.0 

func (b *ShowBuilder) ID(id string) *ShowBuilder

ID sets the target item UUID or built-in list ID.

func (*ShowBuilder) List added in v0.2.0 

func (b *ShowBuilder) List(list ListID) *ShowBuilder

List sets the target to a built-in Things list.

func (*ShowBuilder) Query added in v0.2.0 

func (b *ShowBuilder) Query(query string) *ShowBuilder

Query searches for an area, project, or tag by name. Note: Tasks cannot be shown using query; use ID instead.

type StartBucket 

type StartBucket int

StartBucket represents the scheduling bucket for a task. 

const (
	// StartInbox indicates the task is in the Inbox.
	StartInbox StartBucket = 0
	// StartAnytime indicates the task is scheduled for Anytime.
	StartAnytime StartBucket = 1
	// StartSomeday indicates the task is scheduled for Someday.
	StartSomeday StartBucket = 2
)

func (StartBucket) String 

func (s StartBucket) String() string

String returns the string representation of the StartBucket.

type StartFilter added in v0.2.0 

type StartFilter struct {
	// contains filtered or unexported fields
}

StartFilter provides type-safe start bucket filtering for TaskQuery. Use the terminal methods (Inbox, Anytime, Someday) to set the filter and return to the parent TaskQuery for continued chaining.

func (*StartFilter) Anytime added in v0.2.0 

func (f *StartFilter) Anytime() *TaskQuery

Anytime filters for tasks scheduled as Anytime.

func (*StartFilter) Inbox added in v0.2.0 

func (f *StartFilter) Inbox() *TaskQuery

Inbox filters for tasks in the Inbox.

func (*StartFilter) Someday added in v0.2.0 

func (f *StartFilter) Someday() *TaskQuery

Someday filters for tasks scheduled as Someday.

type Status 

type Status int

Status represents the completion status of a task. 

const (
	// StatusIncomplete indicates the task is not yet completed.
	StatusIncomplete Status = 0
	// StatusCanceled indicates the task was canceled.
	StatusCanceled Status = 2
	// StatusCompleted indicates the task was completed.
	StatusCompleted Status = 3
)

func (Status) IsClosed 

func (s Status) IsClosed() bool

IsClosed returns true if the status indicates a closed (completed or canceled) task.

func (Status) IsOpen 

func (s Status) IsOpen() bool

IsOpen returns true if the status indicates an open (incomplete) task.

func (Status) String 

func (s Status) String() string

String returns the string representation of the Status.

type StatusFilter added in v0.2.0 

type StatusFilter struct {
	// contains filtered or unexported fields
}

StatusFilter provides type-safe status filtering for TaskQuery. Use the terminal methods (Incomplete, Completed, Canceled) to set the filter and return to the parent TaskQuery for continued chaining.

func (*StatusFilter) Any added in v0.2.1 

func (f *StatusFilter) Any() *TaskQuery

Any clears the status filter to include tasks of any status. This is useful when you want to query tasks regardless of their completion state.

func (*StatusFilter) Canceled added in v0.2.0 

func (f *StatusFilter) Canceled() *TaskQuery

Canceled filters for tasks with canceled status.

func (*StatusFilter) Completed added in v0.2.0 

func (f *StatusFilter) Completed() *TaskQuery

Completed filters for tasks with completed status.

func (*StatusFilter) Incomplete added in v0.2.0 

func (f *StatusFilter) Incomplete() *TaskQuery

Incomplete filters for tasks with incomplete status.

type Tag 

type Tag struct {
	UUID     string `json:"uuid"`
	Type     string `json:"type"` // Always "tag"
	Title    string `json:"title"`
	Shortcut string `json:"shortcut,omitempty"`

	// Nested items (populated when include_items=true)
	Items []any `json:"items,omitempty"` // Can contain Area or Task
}

Tag represents a tag in Things 3.

type TagQuery 

type TagQuery struct {
	// contains filtered or unexported fields
}

TagQuery provides a fluent interface for building tag queries.

func (*TagQuery) All 

func (q *TagQuery) All(ctx context.Context) ([]Tag, error)

All executes the query and returns all matching tags.

func (*TagQuery) First 

func (q *TagQuery) First(ctx context.Context) (*Tag, error)

First executes the query and returns the first matching tag.

func (*TagQuery) IncludeItems 

func (q *TagQuery) IncludeItems(include bool) *TagQuery

IncludeItems includes areas and tasks for each tag.

func (*TagQuery) WithParent added in v0.2.1 

func (q *TagQuery) WithParent(parentUUID string) *TagQuery

WithParent filters tags by parent tag UUID. Use this to find child tags of a specific parent tag.

func (*TagQuery) WithTitle 

func (q *TagQuery) WithTitle(title string) *TagQuery

WithTitle filters tags by title.

func (*TagQuery) WithUUID added in v0.2.1 

func (q *TagQuery) WithUUID(uuid string) *TagQuery

WithUUID filters tags by UUID.

type Task 

type Task struct {
	UUID   string   `json:"uuid"`
	Type   TaskType `json:"type"`
	Title  string   `json:"title"`
	Status Status   `json:"status"`
	Notes  string   `json:"notes,omitempty"`
	Start  string   `json:"start,omitempty"` // "Inbox", "Anytime", or "Someday"

	// Trashed indicates whether the task is in the trash.
	Trashed bool `json:"trashed,omitempty"`

	// Relationships
	AreaUUID     *string `json:"area,omitempty"`
	AreaTitle    *string `json:"area_title,omitempty"`
	ProjectUUID  *string `json:"project,omitempty"`
	ProjectTitle *string `json:"project_title,omitempty"`
	HeadingUUID  *string `json:"heading,omitempty"`
	HeadingTitle *string `json:"heading_title,omitempty"`

	// Dates
	// All date/time fields are converted from SQLite string formats to time.Time.
	//
	// StartDate: scheduled start date.
	//   Database: "2024-01-15" (date only, format "YYYY-MM-DD")
	//   Parsed:   time.Time with zero time component
	StartDate *time.Time `json:"start_date,omitempty"`
	// Deadline: task deadline date.
	//   Database: "2024-01-15" (date only, format "YYYY-MM-DD")
	//   Parsed:   time.Time with zero time component
	Deadline *time.Time `json:"deadline,omitempty"`
	// ReminderTime: time-only reminder (date component is zero value).
	//   Database: "14:30" (time only, format "HH:MM")
	//   Parsed:   time.Time with zero date (0000-01-01), only Hour/Minute meaningful
	ReminderTime *time.Time `json:"reminder_time,omitempty"`
	// StopDate: completion or cancellation timestamp.
	//   Database: "2024-01-15 10:30:45" (datetime, format "YYYY-MM-DD HH:MM:SS")
	//   Parsed:   time.Time with full date and time
	StopDate *time.Time `json:"stop_date,omitempty"`
	// Created: task creation timestamp.
	//   Database: "2024-01-15 10:30:45" (datetime, format "YYYY-MM-DD HH:MM:SS")
	//   Parsed:   time.Time with full date and time
	Created time.Time `json:"created"`
	// Modified: last modification timestamp.
	//   Database: "2024-01-15 10:30:45" (datetime, format "YYYY-MM-DD HH:MM:SS")
	//   Parsed:   time.Time with full date and time
	Modified time.Time `json:"modified"`

	// Index values for ordering
	Index      int `json:"index"`
	TodayIndex int `json:"today_index"`

	// Nested items (populated when include_items=true)
	Tags      []string        `json:"tags,omitempty"`
	Checklist []ChecklistItem `json:"checklist,omitempty"`
	Items     []Task          `json:"items,omitempty"` // For projects and headings
}

Task represents a task in Things 3, which can be a to-do, project, or heading.

func (*Task) HasChecklist 

func (t *Task) HasChecklist() bool

HasChecklist returns true if the task has a checklist.

func (*Task) HasTags 

func (t *Task) HasTags() bool

HasTags returns true if the task has any tags.

func (*Task) IsCanceled 

func (t *Task) IsCanceled() bool

IsCanceled returns true if the task status is canceled.

func (*Task) IsCompleted 

func (t *Task) IsCompleted() bool

IsCompleted returns true if the task status is completed.

func (*Task) IsHeading 

func (t *Task) IsHeading() bool

IsHeading returns true if the task is a heading.

func (*Task) IsIncomplete 

func (t *Task) IsIncomplete() bool

IsIncomplete returns true if the task status is incomplete.

func (*Task) IsProject 

func (t *Task) IsProject() bool

IsProject returns true if the task is a project.

func (*Task) IsTodo 

func (t *Task) IsTodo() bool

IsTodo returns true if the task is a to-do item.

type TaskQuery 

type TaskQuery struct {
	// contains filtered or unexported fields
}

TaskQuery provides a fluent interface for building task queries.

func (*TaskQuery) All 

func (q *TaskQuery) All(ctx context.Context) ([]Task, error)

All executes the query and returns all matching tasks.

func (*TaskQuery) ContextTrashed 

func (q *TaskQuery) ContextTrashed(trashed bool) *TaskQuery

ContextTrashed filters tasks by the trash status of their context (project/heading).

func (*TaskQuery) Count 

func (q *TaskQuery) Count(ctx context.Context) (int, error)

Count executes the query and returns the count of matching tasks.

func (*TaskQuery) CreatedWithin added in v0.2.0 

func (q *TaskQuery) CreatedWithin(d Duration) *TaskQuery

CreatedWithin filters tasks created within the specified duration. Example: db.Tasks().CreatedWithin(Days(7)).All(ctx)

func (*TaskQuery) Deadline added in v0.2.0 

func (q *TaskQuery) Deadline() *DateFilter

Deadline returns a DateFilter for deadline filtering. Example: db.Tasks().Deadline().OnOrBefore("2024-12-31").All(ctx)

func (*TaskQuery) First 

func (q *TaskQuery) First(ctx context.Context) (*Task, error)

First executes the query and returns the first matching task.

func (*TaskQuery) HasArea added in v0.2.0 

func (q *TaskQuery) HasArea(has bool) *TaskQuery

HasArea filters tasks by whether they have an area. Pass true to include only tasks with an area. Pass false to include only tasks without an area.

func (*TaskQuery) HasHeading added in v0.2.0 

func (q *TaskQuery) HasHeading(has bool) *TaskQuery

HasHeading filters tasks by whether they have a heading. Pass true to include only tasks with a heading. Pass false to include only tasks without a heading.

func (*TaskQuery) HasProject added in v0.2.0 

func (q *TaskQuery) HasProject(has bool) *TaskQuery

HasProject filters tasks by whether they have a project. Pass true to include only tasks with a project. Pass false to include only tasks without a project.

func (*TaskQuery) HasTag added in v0.2.0 

func (q *TaskQuery) HasTag(has bool) *TaskQuery

HasTag filters tasks by whether they have any tags. Pass true to include only tasks with tags. Pass false to include only tasks without tags.

func (*TaskQuery) InArea 

func (q *TaskQuery) InArea(uuid string) *TaskQuery

InArea filters tasks by a specific area UUID.

func (*TaskQuery) InHeading 

func (q *TaskQuery) InHeading(uuid string) *TaskQuery

InHeading filters tasks by a specific heading UUID.

func (*TaskQuery) InProject 

func (q *TaskQuery) InProject(uuid string) *TaskQuery

InProject filters tasks by a specific project UUID.

func (*TaskQuery) InTag added in v0.2.0 

func (q *TaskQuery) InTag(title string) *TaskQuery

InTag filters tasks by a specific tag title.

func (*TaskQuery) IncludeItems 

func (q *TaskQuery) IncludeItems(include bool) *TaskQuery

IncludeItems includes nested items (checklist for to-dos, tasks for projects/headings).

func (*TaskQuery) OrderByTodayIndex 

func (q *TaskQuery) OrderByTodayIndex() *TaskQuery

OrderByTodayIndex orders results by today index instead of default index.

func (*TaskQuery) Search 

func (q *TaskQuery) Search(query string) *TaskQuery

Search filters tasks by a search query. Searches in task title, notes, and area title.

func (*TaskQuery) Start added in v0.2.0 

func (q *TaskQuery) Start() *StartFilter

Start returns a StartFilter for type-safe start bucket filtering. Example: db.Tasks().Start().Inbox().All(ctx)

func (*TaskQuery) StartDate added in v0.2.0 

func (q *TaskQuery) StartDate() *DateFilter

StartDate returns a DateFilter for start date filtering. Example: db.Tasks().StartDate().Future().All(ctx)

func (*TaskQuery) Status added in v0.2.0 

func (q *TaskQuery) Status() *StatusFilter

Status returns a StatusFilter for type-safe status filtering. Example: db.Tasks().Status().Incomplete().All(ctx)

func (*TaskQuery) StopDate added in v0.2.0 

func (q *TaskQuery) StopDate() *DateFilter

StopDate returns a DateFilter for stop date filtering. Example: db.Tasks().StopDate().Exists(true).All(ctx)

func (*TaskQuery) Trashed 

func (q *TaskQuery) Trashed(trashed bool) *TaskQuery

Trashed filters tasks by trash status. Pass true to include only trashed tasks. Pass false to include only non-trashed tasks.

func (*TaskQuery) Type added in v0.2.0 

func (q *TaskQuery) Type() *TypeFilter

Type returns a TypeFilter for type-safe task type filtering. Example: db.Tasks().Type().Todo().All(ctx)

func (*TaskQuery) WithDeadlineSuppressed 

func (q *TaskQuery) WithDeadlineSuppressed(suppressed bool) *TaskQuery

WithDeadlineSuppressed filters tasks by deadline suppression status.

func (*TaskQuery) WithUUID 

func (q *TaskQuery) WithUUID(uuid string) *TaskQuery

WithUUID filters tasks by UUID.

type TaskType 

type TaskType int

TaskType represents the kind of task in Things 3. Tasks can be to-dos, projects, or headings within projects. 

const (
	// TaskTypeTodo represents a regular to-do item.
	TaskTypeTodo TaskType = 0
	// TaskTypeProject represents a project containing tasks.
	TaskTypeProject TaskType = 1
	// TaskTypeHeading represents a heading within a project.
	TaskTypeHeading TaskType = 2
)

func (TaskType) String 

func (t TaskType) String() string

String returns the string representation of the TaskType.

type TodoBuilder added in v0.2.0 

type TodoBuilder struct {
	// contains filtered or unexported fields
}

TodoBuilder builds URLs for creating new to-dos via the add command.

func (*TodoBuilder) Build added in v0.2.0 

func (b *TodoBuilder) Build() (string, error)

Build returns the Things URL for creating the to-do.

func (*TodoBuilder) Canceled added in v0.2.0 

func (b *TodoBuilder) Canceled(canceled bool) *TodoBuilder

Canceled sets the canceled status.

func (*TodoBuilder) ChecklistItems added in v0.2.0 

func (b *TodoBuilder) ChecklistItems(items ...string) *TodoBuilder

ChecklistItems sets the checklist items.

func (*TodoBuilder) Completed added in v0.2.0 

func (b *TodoBuilder) Completed(completed bool) *TodoBuilder

Completed sets the completion status.

func (*TodoBuilder) CompletionDate added in v0.2.0 

func (b *TodoBuilder) CompletionDate(date time.Time) *TodoBuilder

CompletionDate sets the completion timestamp. Future dates are ignored by Things.

func (*TodoBuilder) CreationDate added in v0.2.0 

func (b *TodoBuilder) CreationDate(date time.Time) *TodoBuilder

CreationDate sets the creation timestamp. Future dates are ignored by Things.

func (*TodoBuilder) Deadline added in v0.2.0 

func (b *TodoBuilder) Deadline(date string) *TodoBuilder

Deadline sets the deadline date in yyyy-mm-dd format.

func (*TodoBuilder) Execute added in v0.3.0 

func (b *TodoBuilder) Execute(ctx context.Context) error

Execute builds and executes the add URL. Returns an error if the URL cannot be built or executed.

func (*TodoBuilder) Heading added in v0.2.0 

func (b *TodoBuilder) Heading(name string) *TodoBuilder

Heading sets the target heading within a project by name.

func (*TodoBuilder) HeadingID added in v0.2.0 

func (b *TodoBuilder) HeadingID(id string) *TodoBuilder

HeadingID sets the target heading within a project by UUID.

func (*TodoBuilder) List added in v0.2.0 

func (b *TodoBuilder) List(name string) *TodoBuilder

List sets the target project or area by name.

func (*TodoBuilder) ListID added in v0.2.0 

func (b *TodoBuilder) ListID(id string) *TodoBuilder

ListID sets the target project or area by UUID.

func (*TodoBuilder) Notes added in v0.2.0 

func (b *TodoBuilder) Notes(notes string) *TodoBuilder

Notes sets the to-do notes/description.

func (*TodoBuilder) Reminder added in v0.3.0 

func (b *TodoBuilder) Reminder(hour, minute int) *TodoBuilder

Reminder sets a reminder time for the to-do. The reminder is combined with the scheduling date (When/WhenDate). If no scheduling date is set, defaults to "today". Hour must be 0-23, minute must be 0-59.

Example: 

scheme.Todo().Title("Meeting").When(WhenTomorrow).Reminder(14, 30) // tomorrow@14:30
scheme.Todo().Title("Call").Reminder(15, 0) // today@15:00 (defaults to today)

func (*TodoBuilder) Reveal added in v0.2.0 

func (b *TodoBuilder) Reveal(reveal bool) *TodoBuilder

Reveal navigates to the newly created to-do.

func (*TodoBuilder) ShowQuickEntry added in v0.2.0 

func (b *TodoBuilder) ShowQuickEntry(show bool) *TodoBuilder

ShowQuickEntry displays the quick entry dialog instead of adding directly.

func (*TodoBuilder) Tags added in v0.2.0 

func (b *TodoBuilder) Tags(tags ...string) *TodoBuilder

Tags sets the tags for the to-do. Tags must already exist in Things.

func (*TodoBuilder) Title added in v0.2.0 

func (b *TodoBuilder) Title(title string) *TodoBuilder

Title sets the to-do title.

func (*TodoBuilder) Titles added in v0.2.0 

func (b *TodoBuilder) Titles(titles ...string) *TodoBuilder

Titles sets multiple to-do titles (creates multiple to-dos). Titles are newline-separated.

func (*TodoBuilder) When added in v0.2.0 

func (b *TodoBuilder) When(when When) *TodoBuilder

When sets the scheduling date.

func (*TodoBuilder) WhenDate added in v0.2.0 

func (b *TodoBuilder) WhenDate(year int, month time.Month, day int) *TodoBuilder

WhenDate sets a specific date for scheduling.

type TypeFilter added in v0.2.0 

type TypeFilter struct {
	// contains filtered or unexported fields
}

TypeFilter provides type-safe task type filtering for TaskQuery. Use the terminal methods (Todo, Project, Heading) to set the filter and return to the parent TaskQuery for continued chaining.

func (*TypeFilter) Heading added in v0.2.0 

func (f *TypeFilter) Heading() *TaskQuery

Heading filters for headings only.

func (*TypeFilter) Project added in v0.2.0 

func (f *TypeFilter) Project() *TaskQuery

Project filters for projects only.

func (*TypeFilter) Todo added in v0.2.0 

func (f *TypeFilter) Todo() *TaskQuery

Todo filters for to-do items only.

type UpdateProjectBuilder added in v0.2.0 

type UpdateProjectBuilder struct {
	// contains filtered or unexported fields
}

UpdateProjectBuilder builds URLs for updating existing projects via the update-project command. Requires authentication token (obtained via AuthScheme).

func (*UpdateProjectBuilder) AddTags added in v0.2.0 

func (b *UpdateProjectBuilder) AddTags(tags ...string) *UpdateProjectBuilder

AddTags adds tags without replacing existing ones.

func (*UpdateProjectBuilder) AppendNotes added in v0.2.0 

func (b *UpdateProjectBuilder) AppendNotes(notes string) *UpdateProjectBuilder

AppendNotes appends text to existing notes.

func (*UpdateProjectBuilder) Area added in v0.2.0 

func (b *UpdateProjectBuilder) Area(name string) *UpdateProjectBuilder

Area moves the project to an area by name.

func (*UpdateProjectBuilder) AreaID added in v0.2.0 

func (b *UpdateProjectBuilder) AreaID(id string) *UpdateProjectBuilder

AreaID moves the project to an area by UUID.

func (*UpdateProjectBuilder) Build added in v0.2.0 

func (b *UpdateProjectBuilder) Build() (string, error)

Build returns the Things URL for updating the project.

func (*UpdateProjectBuilder) Canceled added in v0.2.0 

func (b *UpdateProjectBuilder) Canceled(canceled bool) *UpdateProjectBuilder

Canceled sets the canceled status.

func (*UpdateProjectBuilder) ClearDeadline added in v0.2.0 

func (b *UpdateProjectBuilder) ClearDeadline() *UpdateProjectBuilder

ClearDeadline removes the deadline.

func (*UpdateProjectBuilder) Completed added in v0.2.0 

func (b *UpdateProjectBuilder) Completed(completed bool) *UpdateProjectBuilder

Completed sets the completion status. Note: Setting completed=true is ignored unless all child to-dos are completed or canceled and all headings are archived.

func (*UpdateProjectBuilder) Deadline added in v0.2.0 

func (b *UpdateProjectBuilder) Deadline(date string) *UpdateProjectBuilder

Deadline sets the deadline date.

func (*UpdateProjectBuilder) Execute added in v0.3.0 

func (b *UpdateProjectBuilder) Execute(ctx context.Context) error

Execute builds and executes the update URL. Returns an error if the URL cannot be built or executed.

func (*UpdateProjectBuilder) Notes added in v0.2.0 

func (b *UpdateProjectBuilder) Notes(notes string) *UpdateProjectBuilder

Notes replaces the project notes.

func (*UpdateProjectBuilder) PrependNotes added in v0.2.0 

func (b *UpdateProjectBuilder) PrependNotes(notes string) *UpdateProjectBuilder

PrependNotes prepends text to existing notes.

func (*UpdateProjectBuilder) Reminder added in v0.3.0 

func (b *UpdateProjectBuilder) Reminder(hour, minute int) *UpdateProjectBuilder

Reminder sets a reminder time for the project. The reminder is combined with the scheduling date (When/WhenDate). If no scheduling date is set, defaults to "today". Hour must be 0-23, minute must be 0-59.

func (*UpdateProjectBuilder) Reveal added in v0.2.0 

func (b *UpdateProjectBuilder) Reveal(reveal bool) *UpdateProjectBuilder

Reveal navigates to the project after updating.

func (*UpdateProjectBuilder) Tags added in v0.2.0 

func (b *UpdateProjectBuilder) Tags(tags ...string) *UpdateProjectBuilder

Tags replaces all tags.

func (*UpdateProjectBuilder) Title added in v0.2.0 

func (b *UpdateProjectBuilder) Title(title string) *UpdateProjectBuilder

Title replaces the project title.

func (*UpdateProjectBuilder) When added in v0.2.0 

func (b *UpdateProjectBuilder) When(when When) *UpdateProjectBuilder

When sets the scheduling date.

func (*UpdateProjectBuilder) WhenDate added in v0.2.0 

func (b *UpdateProjectBuilder) WhenDate(year int, month time.Month, day int) *UpdateProjectBuilder

WhenDate sets a specific date for scheduling.

type UpdateTodoBuilder added in v0.2.0 

type UpdateTodoBuilder struct {
	// contains filtered or unexported fields
}

UpdateTodoBuilder builds URLs for updating existing to-dos via the update command. Requires authentication token (obtained via AuthScheme).

func (*UpdateTodoBuilder) AddTags added in v0.2.0 

func (b *UpdateTodoBuilder) AddTags(tags ...string) *UpdateTodoBuilder

AddTags adds tags without replacing existing ones.

func (*UpdateTodoBuilder) AppendChecklistItems added in v0.2.0 

func (b *UpdateTodoBuilder) AppendChecklistItems(items ...string) *UpdateTodoBuilder

AppendChecklistItems appends checklist items.

func (*UpdateTodoBuilder) AppendNotes added in v0.2.0 

func (b *UpdateTodoBuilder) AppendNotes(notes string) *UpdateTodoBuilder

AppendNotes appends text to existing notes.

func (*UpdateTodoBuilder) Build added in v0.2.0 

func (b *UpdateTodoBuilder) Build() (string, error)

Build returns the Things URL for updating the to-do.

func (*UpdateTodoBuilder) Canceled added in v0.2.0 

func (b *UpdateTodoBuilder) Canceled(canceled bool) *UpdateTodoBuilder

Canceled sets the canceled status.

func (*UpdateTodoBuilder) ChecklistItems added in v0.2.0 

func (b *UpdateTodoBuilder) ChecklistItems(items ...string) *UpdateTodoBuilder

ChecklistItems replaces all checklist items.

func (*UpdateTodoBuilder) ClearDeadline added in v0.2.0 

func (b *UpdateTodoBuilder) ClearDeadline() *UpdateTodoBuilder

ClearDeadline removes the deadline.

func (*UpdateTodoBuilder) Completed added in v0.2.0 

func (b *UpdateTodoBuilder) Completed(completed bool) *UpdateTodoBuilder

Completed sets the completion status.

func (*UpdateTodoBuilder) CompletionDate added in v0.2.0 

func (b *UpdateTodoBuilder) CompletionDate(date time.Time) *UpdateTodoBuilder

CompletionDate sets the completion timestamp.

func (*UpdateTodoBuilder) CreationDate added in v0.2.0 

func (b *UpdateTodoBuilder) CreationDate(date time.Time) *UpdateTodoBuilder

CreationDate sets the creation timestamp.

func (*UpdateTodoBuilder) Deadline added in v0.2.0 

func (b *UpdateTodoBuilder) Deadline(date string) *UpdateTodoBuilder

Deadline sets the deadline date. Pass empty string to clear the deadline.

func (*UpdateTodoBuilder) Duplicate added in v0.2.0 

func (b *UpdateTodoBuilder) Duplicate(duplicate bool) *UpdateTodoBuilder

Duplicate duplicates the to-do before updating.

func (*UpdateTodoBuilder) Execute added in v0.3.0 

func (b *UpdateTodoBuilder) Execute(ctx context.Context) error

Execute builds and executes the update URL. Returns an error if the URL cannot be built or executed.

func (*UpdateTodoBuilder) Heading added in v0.2.0 

func (b *UpdateTodoBuilder) Heading(name string) *UpdateTodoBuilder

Heading moves the to-do to a heading by name.

func (*UpdateTodoBuilder) HeadingID added in v0.2.0 

func (b *UpdateTodoBuilder) HeadingID(id string) *UpdateTodoBuilder

HeadingID moves the to-do to a heading by UUID.

func (*UpdateTodoBuilder) List added in v0.2.0 

func (b *UpdateTodoBuilder) List(name string) *UpdateTodoBuilder

List moves the to-do to a project or area by name.

func (*UpdateTodoBuilder) ListID added in v0.2.0 

func (b *UpdateTodoBuilder) ListID(id string) *UpdateTodoBuilder

ListID moves the to-do to a project or area by UUID.

func (*UpdateTodoBuilder) Notes added in v0.2.0 

func (b *UpdateTodoBuilder) Notes(notes string) *UpdateTodoBuilder

Notes replaces the to-do notes.

func (*UpdateTodoBuilder) PrependChecklistItems added in v0.2.0 

func (b *UpdateTodoBuilder) PrependChecklistItems(items ...string) *UpdateTodoBuilder

PrependChecklistItems prepends checklist items.

func (*UpdateTodoBuilder) PrependNotes added in v0.2.0 

func (b *UpdateTodoBuilder) PrependNotes(notes string) *UpdateTodoBuilder

PrependNotes prepends text to existing notes.

func (*UpdateTodoBuilder) Reminder added in v0.3.0 

func (b *UpdateTodoBuilder) Reminder(hour, minute int) *UpdateTodoBuilder

Reminder sets a reminder time for the to-do. The reminder is combined with the scheduling date (When/WhenDate). If no scheduling date is set, defaults to "today". Hour must be 0-23, minute must be 0-59.

func (*UpdateTodoBuilder) Reveal added in v0.2.0 

func (b *UpdateTodoBuilder) Reveal(reveal bool) *UpdateTodoBuilder

Reveal navigates to the to-do after updating.

func (*UpdateTodoBuilder) Tags added in v0.2.0 

func (b *UpdateTodoBuilder) Tags(tags ...string) *UpdateTodoBuilder

Tags replaces all tags.

func (*UpdateTodoBuilder) Title added in v0.2.0 

func (b *UpdateTodoBuilder) Title(title string) *UpdateTodoBuilder

Title replaces the to-do title.

func (*UpdateTodoBuilder) When added in v0.2.0 

func (b *UpdateTodoBuilder) When(when When) *UpdateTodoBuilder

When sets the scheduling date.

func (*UpdateTodoBuilder) WhenDate added in v0.2.0 

func (b *UpdateTodoBuilder) WhenDate(year int, month time.Month, day int) *UpdateTodoBuilder

WhenDate sets a specific date for scheduling.

type When added in v0.2.0 

type When string

When represents scheduling values for the "when" parameter in URL scheme. 

const (
	// WhenToday schedules for today.
	WhenToday When = "today"
	// WhenTomorrow schedules for tomorrow.
	WhenTomorrow When = "tomorrow"
	// WhenEvening schedules for this evening.
	WhenEvening When = "evening"
	// WhenAnytime schedules for anytime.
	WhenAnytime When = "anytime"
	// WhenSomeday schedules for someday.
	WhenSomeday When = "someday"
)

func (When) String added in v0.2.0 

func (w When) String() string

String returns the string representation of the When value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.