things

Documentation

Index

• Constants
• Variables
• func AddProject(params AddProjectParams) error
• func AddTask(params AddParams) error
• func CancelTask(uuid string) error
• func CompleteProject(uuid string) error
• func CompleteTask(uuid string) error
• func ImportJSON(data, authToken string, reveal bool) error
• func IsBuiltinList(name string) bool
• func LogCompleted() error
• func NormalizeDeadline(s string) (string, error)
• func NormalizeWhen(s string) (string, error)
• func ParseListDate(flag, s string) (time.Time, error)
• func SetExecCommandForTest(f func(string, ...string) *exec.Cmd) func(string, ...string) *exec.Cmd
• func Show(params ShowParams) error
• func UpdateProject(params UpdateProjectParams) error
• func UpdateTask(params UpdateParams) error
• type AddParams
• type AddProjectParams
• type ShowParams
• type UpdateParams
• type UpdateProjectParams

Constants

const (
	MaxNotesLen       = 10000
	MaxChecklistItems = 100
	MaxStringLen      = 4000
)

Limits enforced by the Things URL scheme. Checking client-side turns silent truncation / opaque app failures into clean errors.

Rate limit: `add` is capped at 250 items per 10-second rolling window app-side. That check is deferred until `things import` (or another bulk-add surface) lands — single-item `add`/`add-project` invocations can't realistically hit it.

Variables

var BuiltinLists = []string{
	"inbox", "today", "anytime", "upcoming", "someday", "logbook",
	"tomorrow", "deadlines", "repeating", "all-projects", "logged-projects",
}

BuiltinLists are the navigable list IDs the Things URL scheme accepts verbatim as `id=…`. Some (e.g. repeating, all-projects) have no direct DB equivalent — they're app-side views only.

Functions

func AddProject

func AddProject(params AddProjectParams) error

func AddTask

func AddTask(params AddParams) error

func CancelTask

func CancelTask(uuid string) error

func CompleteProject

func CompleteProject(uuid string) error

func CompleteTask

func CompleteTask(uuid string) error

func ImportJSON

func ImportJSON(data, authToken string, reveal bool) error

ImportJSON dispatches a Things JSON payload via `things:///json`. The auth token is always sent when present: it's required for any item with `operation: update`, and harmless on create-only payloads.

func IsBuiltinList

func IsBuiltinList(name string) bool

func LogCompleted

func LogCompleted() error

func NormalizeDeadline

func NormalizeDeadline(s string) (string, error)

NormalizeDeadline validates and canonicalises a --deadline value. The URL scheme accepts a date (YYYY-MM-DD) or English natural-language phrase. RFC3339 inputs are reduced to their date component since deadlines have no time-of-day.

func NormalizeWhen

func NormalizeWhen(s string) (string, error)

NormalizeWhen validates and canonicalises a --when value.

Accepted forms:

• keyword: today, tomorrow, evening, anytime, someday (case-insensitive)
• date: YYYY-MM-DD
• time: HH:MM or H:MM[am|pm]
• date+time: YYYY-MM-DD@HH:MM
• RFC3339: rewritten to YYYY-MM-DD@HH:MM (offset preserved as wall-clock)
• English natural-language phrases: passed through verbatim

Inputs within edit distance 2 of a known keyword are rejected as typos (e.g. "tommorrow", "evning"); anything else passes through so users can keep using NL forms like "friday" or "tonight".

func ParseListDate

func ParseListDate(flag, s string) (time.Time, error)

ParseListDate parses a list-filter date (--on/--from/--to). Accepts YYYY-MM-DD or RFC3339 (reduced to its date portion). Returns midnight in the local timezone — callers convert into whichever representation they need (e.g. model.ThingsDateFromTime). The flag name is used in error messages so the user knows which input was bad.

func SetExecCommandForTest

func SetExecCommandForTest(f func(string, ...string) *exec.Cmd) func(string, ...string) *exec.Cmd

SetExecCommandForTest is a cross-package test seam for stubbing `open` / `osascript` invocations; production code MUST NOT call it. Lives in a non-`_test.go` file because Go does not export `_test.go` symbols to other packages.

func Show

func Show(params ShowParams) error

Show navigates Things to a task, project, area, tag, built-in list, or query result via `things:///show`.

func UpdateProject

func UpdateProject(params UpdateProjectParams) error

func UpdateTask

func UpdateTask(params UpdateParams) error

Types

type AddParams

type AddParams struct {
	Title     string
	Notes     string
	When      string
	Deadline  string
	Tags      string
	Checklist string
	Heading   string
	List      string
}

type AddProjectParams

type AddProjectParams struct {
	Title    string
	Notes    string
	When     string
	Deadline string
	Tags     string
	Area     string
	Todos    string
}

type ShowParams

type ShowParams struct {
	// ID is a UUID or built-in list name (inbox, today, upcoming, …).
	ID string
	// Query triggers app-side quick find instead of a direct show.
	Query string
	// Filter is a comma-separated tag list that scopes the shown view.
	Filter string
	// Background uses `open -g` to avoid bringing Things to the foreground.
	Background bool
}

type UpdateParams

type UpdateParams struct {
	ID        string
	AuthToken string

	Title            *string
	Notes            *string
	PrependNotes     *string
	AppendNotes      *string
	When             *string
	Deadline         *string
	Tags             *string
	AddTags          *string
	Checklist        *string
	PrependChecklist *string
	AppendChecklist  *string
	List             *string
	ListID           *string
	Heading          *string
	HeadingID        *string
	Completed        bool
	Canceled         bool
	Duplicate        bool
	Reveal           bool
}

type UpdateProjectParams

type UpdateProjectParams struct {
	ID        string
	AuthToken string

	Title        *string
	Notes        *string
	PrependNotes *string
	AppendNotes  *string
	When         *string
	Deadline     *string
	Tags         *string
	AddTags      *string
	Area         *string
	AreaID       *string
	Completed    bool
	Canceled     bool
	Duplicate    bool
	Reveal       bool
}