thingscloud

README

things cloud sdk

Things comes with a cloud based API, which can be used to synchronize data between devices. This is a golang SDK to interact with that API, opening the API so that you can enhance your Things experience on iOS and Mac.

Getting Started

Installation

go get github.com/arthursoares/things-cloud-sdk

Quick Start

1. Set up your credentials:

export THINGS_USERNAME='your@email.com'
export THINGS_PASSWORD='yourpassword'

2. Create a simple Go program:

package main

import (
    "fmt"
    "os"
    "time"

    things "github.com/arthursoares/things-cloud-sdk"
)

func main() {
    client := things.New(
        things.APIEndpoint,
        os.Getenv("THINGS_USERNAME"),
        os.Getenv("THINGS_PASSWORD"),
    )

    // Verify credentials
    resp, err := client.Verify()
    if err != nil {
        panic(err)
    }
    fmt.Printf("✓ Connected: %s\n", resp.Email)

    // Get your account's history and sync it (required before writing —
    // the commit's ancestor-index comes from the synced head)
    history, err := client.OwnHistory()
    if err != nil {
        panic(err)
    }
    if err := history.Sync(); err != nil {
        panic(err)
    }

    // Create a task. NewUUID() produces the canonical Base58 identifier
    // format Things requires; Write rejects anything else.
    task := things.TaskActionItem{
        Item: things.Item{
            UUID:   things.NewUUID(),
            Kind:   things.ItemKindTask,
            Action: things.ItemActionCreated,
        },
        P: things.TaskActionItemPayload{
            Title:        things.String("My first task from the SDK!"),
            Status:       things.Status(things.TaskStatusPending),
            Schedule:     things.Schedule(things.TaskScheduleInbox),
            CreationDate: things.Time(time.Now()),
        },
    }

    if err := history.Write(task); err != nil {
        panic(err)
    }
    fmt.Println("✓ Created task")
}

Tip: for writes, prefer things-cli (below) — its payloads replicate real Things.app traffic field-for-field and are verified against HAR captures. The raw SDK write API is lower-level and sends sparse payloads.

3. Run it:

go run main.go

CLI Quick Start

Install and use the command-line tool:

# Install
go install github.com/arthursoares/things-cloud-sdk/cmd/things-cli@latest

# Create a task
things-cli create "Buy groceries" --when today

# List today's tasks
things-cli list --today

# Complete a task
things-cli complete <task-uuid>

Features

• Verify Credentials — validate account access
• Account Management — signup, confirmation, password change, deletion
• History Management — list, create, delete, sync histories
• Item Read/Write — full event-sourced CRUD for tasks, areas, tags, checklist items (supports batching multiple items in one request)
• Task Types — tasks, projects, and headings (action groups within projects)
• Structured Notes — full-text and delta patch support for task notes
• Recurring Tasks — neverending, end on date, end after N times
• Tombstone Deletion — explicit deletion records via Tombstone2 entities
• Device Registration — register app instances for APNS push notifications
• Alarm/Reminders — alarm time offset support on tasks
• State Aggregation — in-memory state built from history items, with queries for projects, headings, subtasks, areas, tags, and checklist items
• Persistent Sync Engine — SQLite-backed incremental sync with semantic change detection

CLI

things-cli is a command-line tool for interacting with Things Cloud directly.

Setup

export THINGS_USERNAME='your@email.com'
export THINGS_PASSWORD='yourpassword'
go build -o things-cli ./cmd/things-cli/

Commands

# Read
things-cli list [--today] [--inbox] [--anytime] [--someday] [--upcoming] [--search QUERY] [--area NAME] [--project NAME]
things-cli today
things-cli inbox
things-cli anytime
things-cli someday
things-cli upcoming
things-cli search <query>
things-cli show <uuid>
things-cli areas
things-cli projects
things-cli tags

# Optional read-state cache location
export THINGS_CLI_CACHE=/path/to/things-cli-state.json

# Create
things-cli create "Title" [--note ...] [--when today|anytime|someday|inbox] \
  [--deadline YYYY-MM-DD] [--scheduled YYYY-MM-DD] \
  [--project UUID] [--heading UUID] [--area UUID] \
  [--tags UUID,...] [--type task|project|heading]
things-cli create-area "Name"
things-cli create-tag "Name" [--shorthand KEY] [--parent UUID]

# Modify
things-cli edit <uuid> [--title ...] [--note ...] [--when ...] [--deadline ...] [--scheduled YYYY-MM-DD]
things-cli complete <uuid>
things-cli trash <uuid>
things-cli purge <uuid>
things-cli move-to-today <uuid>

# Batch (all operations in one HTTP request - much faster!)
# UUIDs must be canonical Base58 identifiers, as returned by create/list
echo '[{"cmd":"complete","uuid":"BXmAcvS6yK1eDhW31MuZrL"},{"cmd":"trash","uuid":"VJ1edXTP9q3PmFDUuy8EQh"}]' | things-cli batch

--scheduled uses the local calendar date: future dates appear in Upcoming, while today and past dates use the Today/Anytime schedule. If --when is also provided, its schedule takes precedence and --scheduled still supplies the date. For batch creates, pass the date as "extra":{"scheduled":"YYYY-MM-DD"}.

Examples

Write commands reject invalid relationship identifiers, schedule/type names, and calendar dates before sending a commit. Tag IDs must be canonical Base58 with no surrounding whitespace. Batch input is validated in full before its single commit; see CLI write validation for supported options and batch extra rules.

# Create a project with tasks
things-cli create "My Project" --type project --when anytime
# → {"status":"created","uuid":"BXmAcvS6yK1eDhW31MuZrL","title":"My Project"}

things-cli create "First Task" --project BXmAcvS6yK1eDhW31MuZrL --when today --note "Details here"

# Create an area and assign tasks
things-cli create-area "Work"
things-cli create "Review PR" --area <area-uuid> --when today --deadline 2026-02-15

# Batch operations (50 ops in ~2 sec instead of ~2-3 min)
echo '[
  {"cmd": "create", "title": "Task 1"},
  {"cmd": "create", "title": "Task 2"},
  {"cmd": "move-to-project", "uuid": "VJ1edXTP9q3PmFDUuy8EQh", "project": "BXmAcvS6yK1eDhW31MuZrL"},
  {"cmd": "complete", "uuid": "FQxaqvLBkbR5q2Q5oRoknc"}
]' | things-cli batch

Advanced SDK Usage

Working with Histories and Items

package main

import (
    "fmt"
    "os"

    things "github.com/arthursoares/things-cloud-sdk"
)

func main() {
    client := things.New(
        things.APIEndpoint,
        os.Getenv("THINGS_USERNAME"),
        os.Getenv("THINGS_PASSWORD"),
    )

    history, _ := client.OwnHistory()
    _ = history.Sync()

    // Create a project, then a task referencing it
    projectID := things.NewUUID()
    project := things.TaskActionItem{
        Item: things.Item{UUID: projectID, Kind: things.ItemKindTask, Action: things.ItemActionCreated},
        P: things.TaskActionItemPayload{
            Title:    things.String("My Project"),
            Type:     things.TaskTypePtr(things.TaskTypeProject),
            Schedule: things.Schedule(things.TaskScheduleAnytime),
        },
    }

    task := things.TaskActionItem{
        Item: things.Item{UUID: things.NewUUID(), Kind: things.ItemKindTask, Action: things.ItemActionCreated},
        P: things.TaskActionItemPayload{
            Title:         things.String("First task"),
            ParentTaskIDs: &[]string{projectID},
            Schedule:      things.Schedule(things.TaskScheduleAnytime),
        },
    }

    // One commit per Write; each item needs a unique canonical UUID —
    // Write() validates both and refuses anything that would corrupt
    // the sync history.
    if err := history.Write(project, task); err != nil {
        panic(err)
    }
    fmt.Println("✓ Created project with a task")
}

See the example/ directory for more complete examples including history sync, task creation, and state aggregation.

Persistent Sync Engine

The sync package provides a SQLite-backed sync engine that tracks "what changed since last sync" — perfect for building agents, automations, or dashboards that react to Things changes.

package main

import (
    "fmt"
    "os"
    things "github.com/arthursoares/things-cloud-sdk"
    "github.com/arthursoares/things-cloud-sdk/sync"
)

func main() {
    client := things.New(
        things.APIEndpoint,
        os.Getenv("THINGS_USERNAME"),
        os.Getenv("THINGS_PASSWORD"),
    )

    // Open persistent sync database
    syncer, _ := sync.Open("things.db", client)
    defer syncer.Close()

    // Fetch changes since last sync
    changes, _ := syncer.Sync()

    for _, c := range changes {
        switch v := c.(type) {
        case sync.TaskCreated:
            fmt.Printf("New task: %s\n", v.Task.Title)
        case sync.TaskCompleted:
            fmt.Printf("Completed: %s\n", v.Task.Title)
        case sync.TaskMovedToToday:
            fmt.Printf("Moved to Today: %s\n", v.Task.Title)
        }
    }

    // Query current state
    state := syncer.State()
    inbox, _ := state.TasksInInbox(sync.QueryOpts{})
    projects, _ := state.AllProjects(sync.QueryOpts{})
}

Task7 writes, reads, and recovery

The CLI uses Task7 for validated ordinary task, project, and heading creation and modification. History.Write also accepts explicit ItemKindTask7 envelopes within that scope. It checks existing update targets against raw history and rejects recurring or unknown targets before posting. This adds a history read for update requests. Direct recurrence configuration, note-delta writes, and Task7 deletion events remain unsupported; other entity formats, including Tombstone2 purge, are unchanged.

Older or sparse task histories that never explicitly establish rr, rp, and rt are also rejected by CLI updates, even when the task may be ordinary. This is a compatibility limit of the first Task7 rollout: the checker does not guess missing recurrence state and does not silently retry through Task6.

Existing SDK callers retain ItemKindTask == "Task6" and their previous write behavior. The readers accept both versions and older task kinds. Migrating outgoing writes does not rewrite stored tasks or history. See Task7 write policy for the exact boundary, SDK usage, and mixed-version live evidence.

The first read after this upgrade replays state built by an older task reader:

• things-cli saves the old JSON cache as <cache-path>.before-replay-<random>.bak, then atomically replaces the cache after successful replay.
• The SQLite sync engine keeps opening databases offline. On the next Sync(), it detects the old replay generation even if the cursor is already at the cloud head. It creates a consistent <database-path>.task7-backup-<random> backup, rebuilds derived state in memory, and installs it in one transaction.
• Existing SQLite change-log rows, IDs, and timestamps are retained. Historical replay below the old cursor produces no duplicate log entries or notifications. Old Task7 UnknownChange rows remain audit evidence; newly fetched events after that cursor are logged normally.
• Failed or incomplete replay leaves the existing database/cache available for retry. Backups are kept with owner-only permissions. Each SQLite attempt snapshots the current database; identical validated snapshots are deduplicated by full content so repeated failures do not accumulate identical backups. Staging requires memory proportional to the rebuilt state, and each attempt needs temporary free space for a full database snapshot.

Call Sync() before relying on database queries after upgrading: Open() does not perform network recovery. A future unsupported task kind returns an incomplete-sync error instead of silently advancing the cursor. Diagnostics do not include task payloads.

CLI cache writes use atomic replacement and optimistic change detection, not a cross-process lock. Concurrent readers can replace one another's complete cache snapshots; a later read catches up from the saved cursor. Give concurrent consumers distinct THINGS_CLI_CACHE paths if they must not share cache writes. SQLite recovery separately checks its saved metadata within the installation transaction.

Scheduled dates now use sr only; tir is a separate Today ordering reference date. Omitted task fields preserve prior values, while explicit nulls clear supported nullable dates, notes, and relationships. Modern repeater (rp) semantics remain incompletely verified; unknown wire fields remain available in raw Item.P and are not newly interpreted by the task model. The existing ReminderDate API field tagged rmd is a legacy misnomer for repeater migration date.

Semantic Change Types

The sync engine detects 40+ semantic change types:

Category	Changes
Task Lifecycle	TaskCreated, TaskCompleted, TaskUncompleted, TaskTrashed, TaskDeleted
Task Movement	TaskMovedToInbox, TaskMovedToToday, TaskMovedToAnytime, TaskMovedToSomeday, TaskMovedToUpcoming
Task Organization	TaskMovedToProject, TaskMovedToArea, TaskMovedUnderHeading, TaskTagsChanged
Task Details	TaskTitleChanged, TaskNoteChanged, TaskDeadlineSet, TaskDeadlineRemoved
Projects	ProjectCreated, ProjectCompleted, ProjectTrashed, ProjectDeleted
Areas & Tags	AreaCreated, AreaDeleted, TagCreated, TagDeleted
Checklists	ChecklistItemCreated, ChecklistItemCompleted, ChecklistItemDeleted

State Queries

state := syncer.State()

// Query by location
inbox, _ := state.TasksInInbox(sync.QueryOpts{})
today, _ := state.TasksInToday(sync.QueryOpts{})
anytime, _ := state.TasksInAnytime(sync.QueryOpts{})
someday, _ := state.TasksInSomeday(sync.QueryOpts{})
upcoming, _ := state.TasksInUpcoming(sync.QueryOpts{})

// Query by container
tasks, _ := state.TasksInProject(projectUUID, sync.QueryOpts{})
tasks, _ := state.TasksInArea(areaUUID, sync.QueryOpts{})
tasks, _ := state.TasksUnderHeading(headingUUID, sync.QueryOpts{})
headings, _ := state.HeadingsInProject(projectUUID, sync.QueryOpts{})

// Query by tag or text
tasks, _ := state.TasksWithTag(tagUUID, sync.QueryOpts{})
tasks, _ := state.SearchTasks("invoice", sync.QueryOpts{})

// List all
projects, _ := state.AllProjects(sync.QueryOpts{})
headings, _ := state.AllHeadings(sync.QueryOpts{})
areas, _ := state.AllAreas(sync.QueryOpts{})
tags, _ := state.AllTags(sync.QueryOpts{})

Change Log Queries

// Changes in last hour
changes, _ := syncer.ChangesSince(time.Now().Add(-1 * time.Hour))

// Changes for a specific task
changes, _ := syncer.ChangesForEntity(taskUUID)

// Changes since server index
changes, _ := syncer.ChangesSinceIndex(150)

Wire Format Notes

Key findings from reverse engineering the Things Cloud sync protocol:

• UUIDs must be Base58-encoded (Bitcoin alphabet: 123456789ABCDEFGH...). Standard UUID strings or other encodings will crash Things.app during sync.
• md (modification date) must be null on creates. Set timestamps only on updates.
• Schedule field (st): 0 = Inbox, 1 = Anytime/Today (with sr/tir dates = Today), 2 = Someday/Upcoming (with dates = Upcoming).
• Status field (ss): 0 = Pending, 2 = Canceled, 3 = Completed. Don't confuse with st (schedule)!
• Headings (tp=2) must have st=1 (anytime). st=0 (inbox) crashes Things.app.
• Tasks in projects, headings, or areas should default to st=1 (anytime) — they've been triaged out of inbox.
• Kind strings: Task7 for verified CLI task writes; Task6 remains supported for existing SDK callers; Tag4, ChecklistItem3, Area3, Tombstone2 for other entities.

Since v0.3.0 the SDK enforces the identifier rules instead of trusting callers: things.NewUUID() generates canonical Base58 identifiers (one leading 1 per leading zero byte — a subtlety whose absence used to corrupt ~1 in 256 creates), things.ValidateUUID() checks any identifier, and History.Write() refuses items with invalid or duplicate UUIDs before anything reaches the server.

See docs/client-side-bugs.md for the full investigation and crash analysis.

Architecture

The SDK models all changes as immutable Items (events). A History is a sync stream identified by a UUID. The client pushes/pulls Items through Histories, inspired by operational transformations and Git's internals.

TODO

• Repeat after completion
• Persistent state storage (see sync package)

Note

As there is no official API documentation available all requests need to be reverse engineered, which takes some time. Feel free to contribute and improve & extend this implementation.

Documentation

Index

• Constants
• Variables
• func ApplyPatches(original string, patches []NotePatch) string
• func ApplyPatchesChecked(original string, patches []NotePatch) (string, error)
• func DecodeUUID(s string) (uuid.UUID, error)
• func EncodeLegacyIdentifier(legacyID string) string
• func EncodeUUID(u uuid.UUID) string
• func NewUUID() string
• func String(str string) *string
• func ValidateTaskReadKinds(items []Item) error
• func ValidateUUID(s string) error
• type AccountService
  • func (s *AccountService) AcceptSLA() error
  • func (s *AccountService) ChangePassword(newPassword string) (*Client, error)
  • func (s *AccountService) Confirm(code string) error
  • func (s *AccountService) Delete() error
  • func (s *AccountService) SignUp(email, password string) (*Client, error)
• type AccountStatus
• type AppInstanceRequest
• type Area
• type AreaActionItem
  • func (item AreaActionItem) UUID() string
• type AreaActionItemPayload
• type Boolean
  • func (b *Boolean) MarshalJSON() ([]byte, error)
  • func (b *Boolean) UnmarshalJSON(bs []byte) error
• type CheckListActionItem
  • func (item CheckListActionItem) UUID() string
• type CheckListActionItemPayload
• type CheckListItem
• type Client
  • func New(endpoint, email, password string) *Client
  • func (c *Client) CreateHistory() (*History, error)
  • func (c *Client) Histories() ([]*History, error)
  • func (c *Client) History(id string) (*History, error)
  • func (c *Client) HistoryWithID(id string) *History
  • func (c *Client) OwnHistory() (*History, error)
  • func (c *Client) RegisterAppInstance(req AppInstanceRequest) error
  • func (c *Client) Verify() (*VerifyResponse, error)
• type ClientInfo
  • func DefaultClientInfo() ClientInfo
• type FrequencyUnit
• type HTTPError
  • func (e *HTTPError) Error() string
• type History
  • func (h *History) Delete() error
  • func (h *History) Items(opts ItemsOptions) ([]Item, bool, error)
  • func (h *History) Sync() error
  • func (h *History) Write(items ...Identifiable) error
• type Identifiable
• type Item
• type ItemAction
  • func (i ItemAction) String() string
• type ItemKind
• type ItemsOptions
• type Note
• type NotePatch
• type RepeaterConfiguration
  • func (c RepeaterConfiguration) ComputeFirstScheduledAt(t time.Time) time.Time
  • func (c RepeaterConfiguration) IsNeverending() bool
  • func (c RepeaterConfiguration) NextScheduledAt(repeat int) time.Time
• type RepeaterDetailConfiguration
• type Setting
• type Tag
• type TagActionItem
  • func (t TagActionItem) UUID() string
• type TagActionItemPayload
• type Task
• type TaskActionItem
  • func (t TaskActionItem) UUID() string
• type TaskActionItemPayload
• type TaskReadPayload
  • func DecodeTaskReadPayload(raw json.RawMessage) (TaskReadPayload, error)
  • func (p TaskReadPayload) ApplyNulls(task *Task)
  • func (p TaskReadPayload) ResolveNote(current string) (string, error)
• type TaskSchedule
  • func Schedule(val TaskSchedule) *TaskSchedule
  • func (i TaskSchedule) String() string
• type TaskStatus
  • func Status(val TaskStatus) *TaskStatus
  • func (i TaskStatus) String() string
• type TaskType
  • func TaskTypePtr(val TaskType) *TaskType
• type Timestamp
  • func Time(val time.Time) *Timestamp
  • func (t *Timestamp) Format(layout string) string
  • func (t *Timestamp) MarshalJSON() ([]byte, error)
  • func (t *Timestamp) Time() *time.Time
  • func (t *Timestamp) UnmarshalJSON(bs []byte) error
• type TombstoneActionItem
  • func (t TombstoneActionItem) UUID() string
• type TombstoneActionItemPayload
• type UnsupportedTaskKindError
  • func (e *UnsupportedTaskKindError) Error() string
• type VerifyResponse

Examples

• Client.Histories
• Client.Verify
• History.Items

Constants

const (
	// APIEndpoint is the public culturedcode https endpoint
	APIEndpoint = "https://cloud.culturedcode.com"
)

const NoteTypeDelta = 2

NoteTypeDelta indicates a note with incremental patches

const NoteTypeFullText = 1

NoteTypeFullText indicates a note with complete text

const TaskReplayVersion = 3

TaskReplayVersion identifies the task read semantics used to build derived state. Cached state from older generations must be replayed from scratch.

const ThingsUserAgent = "ThingsMac/32209501"

ThingsUserAgent is the http user-agent header set by things for mac

Variables

var (
	// ErrUnauthorized is returned by the API when the credentials are wrong
	ErrUnauthorized = errors.New("unauthorized")
)

Functions

func ApplyPatches

func ApplyPatches(original string, patches []NotePatch) string

ApplyPatches applies a series of text patches using UTF-8 byte offsets.

func ApplyPatchesChecked

func ApplyPatchesChecked(original string, patches []NotePatch) (string, error)

ApplyPatchesChecked applies byte-offset patches and rejects any patch that leaves the note in an invalid UTF-8 state. ApplyPatches remains available for callers that rely on its historical unchecked behavior.

func DecodeUUID

func DecodeUUID(s string) (uuid.UUID, error)

DecodeUUID decodes a canonical Base58 identifier back into a UUID. It rejects strings that are not canonical encodings of exactly 16 bytes.

func EncodeLegacyIdentifier

func EncodeLegacyIdentifier(legacyID string) string

EncodeLegacyIdentifier derives the current Base58 identifier for an object created before Things Cloud's identifier migration. Old history items (Task3, Task4, Area2, ...) key objects by identifier strings such as uppercase UUIDs; newer items (Task6, ...) key the same objects by

Base58(SHA1(legacyID)[:16])

The history contains no records linking the two generations; this derivation is the only link. legacyID must be the identifier text exactly as stored in the history: hashing is byte-exact, so any normalization (such as lowercasing a UUID) yields a different identifier. SHA-1 mirrors the derivation Things itself performs; it is not a security primitive here.

Recurring-task instances use composite identifiers of the form <uuid>-YYYYMMDD and hash in two steps: first the <uuid> prefix alone, then its raw 16-byte digest followed by the "-YYYYMMDD" text.

The empty string is returned unchanged: a malformed item should keep an obviously-bogus key rather than gain a plausible-looking derived one.

func EncodeUUID

func EncodeUUID(u uuid.UUID) string

EncodeUUID encodes a UUID as canonical Base58: one leading '1' per leading zero byte, matching the identifiers Things.app itself emits.

func NewUUID

func NewUUID() string

NewUUID returns a new random identifier in the canonical Base58 wire format expected by Things Cloud.

func String

func String(str string) *string

String returns a pointer to a string

func ValidateTaskReadKinds

func ValidateTaskReadKinds(items []Item) error

ValidateTaskReadKinds preflights an entire batch before any task state is mutated. Unrelated unknown entities retain their existing handling.

func ValidateUUID

func ValidateUUID(s string) error

ValidateUUID reports whether s is a canonical Base58-encoded 16-byte identifier safe to write to Things Cloud.

Types

type AccountService

type AccountService service

AccountService allows account specific interaction with thingscloud

func (*AccountService) AcceptSLA

func (s *AccountService) AcceptSLA() error

func (*AccountService) ChangePassword

func (s *AccountService) ChangePassword(newPassword string) (*Client, error)

ChangePassword allows you to change your account password. Because things does not work with sessions you need to create a new client instance after executing this method

func (*AccountService) Confirm

func (s *AccountService) Confirm(code string) error

Confirm finishes the account creation by providing the email token send by thingscloud

func (*AccountService) Delete

func (s *AccountService) Delete() error

Delete deletes your current thingscloud account. This cannot be reversed

func (*AccountService) SignUp

func (s *AccountService) SignUp(email, password string) (*Client, error)

SignUp creates a new thingscloud account and returns a configured client

type AccountStatus

type AccountStatus string

AccountStatus describes possible thingscloud account statuses

const (
	// AccountStatusActive is for active accounts
	AccountStatusActive AccountStatus = "SYAccountStatusActive"
)

type AppInstanceRequest

type AppInstanceRequest struct {
	AppInstanceID string `json:"-"`
	HistoryKey    string `json:"history-key"`
	APNSToken     string `json:"apns-token"`
	AppID         string `json:"app-id"`
	Dev           bool   `json:"dev"`
}

AppInstanceRequest describes the payload for registering a device for push notifications

type Area

type Area struct {
	UUID  string
	Title string
	Tags  []*Tag
	Tasks []*Task
}

Area describes an Area inside things. An Area is a container for tasks 0|uuid|TEXT|0||1 1|title|TEXT|0||0 2|visible|INTEGER|0||0 3|index|INTEGER|0||0

type AreaActionItem

type AreaActionItem struct {
	Item
	P AreaActionItemPayload `json:"p"`
}

AreaActionItem describes an event on an Area

func (AreaActionItem) UUID

func (item AreaActionItem) UUID() string

UUID returns the UUID of the modified Area

type AreaActionItemPayload

type AreaActionItemPayload struct {
	IX     *int     `json:"ix,omitempty"`
	Title  *string  `json:"tt,omitempty"`
	TagIDs []string `json:"tg,omitempty"`
}

AreaActionItemPayload describes the payload for modifying Areas

type Boolean

type Boolean bool

Boolean allows integers to be parsed into booleans, where 1 means true and 0 means false

func (*Boolean) MarshalJSON

func (b *Boolean) MarshalJSON() ([]byte, error)

MarshalJSON takes a boolean and serializes it as an integer

func (*Boolean) UnmarshalJSON

func (b *Boolean) UnmarshalJSON(bs []byte) error

UnmarshalJSON takes an int and creates a boolean instance

type CheckListActionItem

type CheckListActionItem struct {
	Item
	P CheckListActionItemPayload `json:"p"`
}

CheckListActionItem describes an event on a check list item

func (CheckListActionItem) UUID

func (item CheckListActionItem) UUID() string

UUID returns the UUID of the modified CheckListItem

type CheckListActionItemPayload

type CheckListActionItemPayload struct {
	CreationDate     *Timestamp      `json:"cd,omitempty"`
	ModificationDate *Timestamp      `json:"md,omitempty"`
	Index            *int            `json:"ix"`
	Status           *TaskStatus     `json:"ss,omitempty"`
	Title            *string         `json:"tt,omitempty"`
	CompletionDate   *Timestamp      `json:"sp,omitempty"`
	TaskIDs          *[]string       `json:"ts,omitempty"`
	Leavable         *bool           `json:"lt,omitempty"`
	ExtensionData    json.RawMessage `json:"xx,omitempty"`
}

CheckListActionItemPayload describes the payload for modifying CheckListItems

type CheckListItem

type CheckListItem struct {
	UUID             string
	CreationDate     time.Time
	ModificationDate *time.Time
	Status           TaskStatus
	Title            string
	Index            int
	CompletionDate   *time.Time
	TaskIDs          []string
}

CheckListItem describes a check list item 0|uuid|TEXT|0||1 1|userModificationDate|REAL|0||0 2|creationDate|REAL|0||0 3|title|TEXT|0||0 4|status|INTEGER|0||0 5|stopDate|REAL|0||0 6|index|INTEGER|0||0 7|task|TEXT|0||0

type Client

type Client struct {
	Endpoint string
	EMail    string

	ClientInfo ClientInfo
	Debug      bool

	Accounts *AccountService
	// contains filtered or unexported fields
}

Client is a culturedcode cloud client. It can be used to interact with the things cloud to manage your data.

func New

func New(endpoint, email, password string) *Client

New initializes a things client

func (*Client) CreateHistory

func (c *Client) CreateHistory() (*History, error)

CreateHistory requests a new history key

func (*Client) Histories

func (c *Client) Histories() ([]*History, error)

Histories requests all known history keys

Example

client := New(APIEndpoint, os.Getenv("THINGS_USERNAME"), os.Getenv("THINGS_PASSWORD"))

histories, err := client.Histories()
if err != nil {
	log.Printf("Failed loading histories: %q", err.Error())
}

for _, history := range histories {
	if err := history.Sync(); err != nil {
		log.Printf("Failed syncing history: %q", err.Error())
	}
}

func (*Client) History

func (c *Client) History(id string) (*History, error)

History requests a specific history

func (*Client) HistoryWithID

func (c *Client) HistoryWithID(id string) *History

HistoryWithID creates a History object with the given ID without making a network call. Use this when you already know the history ID (e.g., from a previous sync).

func (*Client) OwnHistory

func (c *Client) OwnHistory() (*History, error)

OwnHistory returns the clients own history

func (*Client) RegisterAppInstance

func (c *Client) RegisterAppInstance(req AppInstanceRequest) error

RegisterAppInstance registers a device for push notifications via APNS

func (*Client) Verify

func (c *Client) Verify() (*VerifyResponse, error)

Verify checks that the provided API credentials are valid.

Example

client := New(APIEndpoint, os.Getenv("THINGS_USERNAME"), os.Getenv("THINGS_PASSWORD"))

_, err := client.Verify()
if err != nil {
	log.Printf("Invalid Credentials: %q", err.Error())
}

type ClientInfo

type ClientInfo struct {
	DeviceModel string `json:"dm"`
	LocalRegion string `json:"lr"`
	NF          bool   `json:"nf"`
	NK          bool   `json:"nk"`
	AppName     string `json:"nn"`
	AppVersion  string `json:"nv"`
	OSName      string `json:"on"`
	OSVersion   string `json:"ov"`
	PrimaryLang string `json:"pl"`
	UserLocale  string `json:"ul"`
}

ClientInfo represents the device metadata sent in the things-client-info header.

func DefaultClientInfo

func DefaultClientInfo() ClientInfo

DefaultClientInfo returns a ClientInfo with default values matching a typical Mac client.

type FrequencyUnit

type FrequencyUnit int64

FrequencyUnit describes recurring frequencies

var (
	// FrequencyUnitDaily occurs every n days
	FrequencyUnitDaily FrequencyUnit = 16
	// FrequencyUnitWeekly occurs every n weeks
	FrequencyUnitWeekly FrequencyUnit = 256
	// FrequencyUnitMonthly occurs every n months
	FrequencyUnitMonthly FrequencyUnit = 8
	// FrequencyUnitYearly occurs every n years
	FrequencyUnitYearly FrequencyUnit = 4
)

type HTTPError

type HTTPError struct {
	StatusCode int
	Status     string
}

HTTPError is returned when the Things Cloud server responds with an unexpected status code. Callers can inspect StatusCode with errors.As to decide whether a request is worth retrying.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type History

type History struct {
	ID                     string
	Client                 *Client
	LatestServerIndex      int
	LoadedServerIndex      int
	LatestSchemaVersion    int
	EndTotalContentSize    int
	LatestTotalContentSize int
}

History represents a synchronization stream. It's identified with a uuid v4

func (*History) Delete

func (h *History) Delete() error

Delete destroys a history Note that thingscloud will always return 202, even if the key is unknown

func (*History) Items

func (h *History) Items(opts ItemsOptions) ([]Item, bool, error)

Items fetches changes from thingscloud. Every change contains multiple items which have been modified. The Items method unwraps these objects and returns a list instead.

Note that if a item was changed multiple times it will be present multiple times in the result too.

Example

client := New(APIEndpoint, os.Getenv("THINGS_USERNAME"), os.Getenv("THINGS_PASSWORD"))

histories, err := client.Histories()
if err != nil {
	log.Printf("Failed loading histories: %q", err.Error())
}
history := histories[0]

items, _, err := history.Items(ItemsOptions{})
if err != nil {
	log.Printf("Failed loading items: %q", err.Error())
}

log.Printf("got %d items.", len(items))

func (*History) Sync

func (h *History) Sync() error

Sync ensures the history object is able to write to things

func (*History) Write

func (h *History) Write(items ...Identifiable) error

type Identifiable

type Identifiable interface {
	UUID() string
}

Identifiable abstracts different thingscloud write requests. As we need to provide a map indexed by UUID, all we care about is the ID of the change, not the change itself

type Item

type Item struct {
	UUID           string          `json:"-"`
	P              json.RawMessage `json:"p"`
	Kind           ItemKind        `json:"e"`
	Action         ItemAction      `json:"t"`
	ServerIndex    int             `json:"-"`
	HasServerIndex bool            `json:"-"`
}

Item is an event in thingscloud. Every action inside things generates an Item. Common items are the creation of a task, area or checklist, as well as modifying attributes or marking things as done.

type ItemAction

type ItemAction int

ItemAction describes possible actions on Items

const (
	// ItemActionCreated is used to indicate a new Item was created
	ItemActionCreated ItemAction = iota
	// ItemActionModified is used to indicate an existing Item was modified
	ItemActionModified ItemAction = 1
	// ItemActionDeleted is used as a tombstone for an Item
	ItemActionDeleted ItemAction = 2
)

func (ItemAction) String

func (i ItemAction) String() string

type ItemKind

type ItemKind string

ItemKind describes the different types things cloud supports

var (
	// ItemKindChecklistItem identifies a CheckList
	ItemKindChecklistItem  ItemKind = "ChecklistItem"
	ItemKindChecklistItem2 ItemKind = "ChecklistItem2"
	ItemKindChecklistItem3 ItemKind = "ChecklistItem3"
	// ItemKindTask identifies a Task or Subtask
	ItemKindTask ItemKind = "Task6"
	// ItemKindTask7 identifies the explicitly validated Task7 read/write scope.
	// ItemKindTask remains Task6 for compatibility with existing callers.
	ItemKindTask7     ItemKind = "Task7"
	ItemKindTask4     ItemKind = "Task4"
	ItemKindTask3     ItemKind = "Task3"
	ItemKindTaskPlain ItemKind = "Task"
	// ItemKindArea identifies an Area in the legacy Area2 encoding.
	//
	// Deprecated: never WRITE items with this kind — Things.app silently
	// ignores Area2 creates and manufactures a duplicate area with a new
	// UUID. Use ItemKindArea3. Reading Area2 items from old histories is
	// still supported.
	ItemKindArea      ItemKind = "Area2"
	ItemKindArea3     ItemKind = "Area3"
	ItemKindAreaPlain ItemKind = "Area"
	// ItemKindSettings  identifies a setting
	ItemKindSettings ItemKind = "Settings3"
	// ItemKindTag identifies a Tag
	ItemKindTag            ItemKind = "Tag3"
	ItemKindTag4           ItemKind = "Tag4"
	ItemKindTagPlain       ItemKind = "Tag"
	ItemKindTombstone      ItemKind = "Tombstone2"
	ItemKindTombstonePlain ItemKind = "Tombstone"
)

type ItemsOptions

type ItemsOptions struct {
	StartIndex int
}

ItemsOptions allows a client to pickup changes from a specific index

type Note

type Note struct {
	TypeTag  string      `json:"_t"`
	Type     int         `json:"t"`
	Checksum int64       `json:"ch,omitempty"`
	Value    string      `json:"v,omitempty"`
	Patches  []NotePatch `json:"ps,omitempty"`
}

Note describes a structured note as used by the Things API

type NotePatch

type NotePatch struct {
	Replacement string `json:"r"`
	Position    int    `json:"p"`
	Length      int    `json:"l"`
	Checksum    int64  `json:"ch"`
}

NotePatch describes a single text replacement operation

type RepeaterConfiguration

type RepeaterConfiguration struct {
	FirstScheduledAt    *Timestamp                    `json:"ia,omitempty"`
	RepeatCount         *int64                        `json:"rc,omitempty"`
	FrequencyUnit       FrequencyUnit                 `json:"fu"`
	FrequencyAmplitude  int64                         `json:"fa"`
	DetailConfiguration []RepeaterDetailConfiguration `json:"of"`
	LastScheduledAt     *Timestamp                    `json:"ed,omitempty"`
	Version             int                           `json:"rrv,omitempty"`
	Type                int                           `json:"tp,omitempty"`
	TimeShift           int                           `json:"ts,omitempty"`
	StartReference      *Timestamp                    `json:"sr,omitempty"`
}

RepeaterConfiguration configures the recurring rules of a task/ project

func (RepeaterConfiguration) ComputeFirstScheduledAt

func (c RepeaterConfiguration) ComputeFirstScheduledAt(t time.Time) time.Time

ComputeFirstScheduledAt calculates the first occurrence of a recurring rule based on the pattern This value has to be stored as FirstScheduledAt per thingscloud convention

func (RepeaterConfiguration) IsNeverending

func (c RepeaterConfiguration) IsNeverending() bool

IsNeverending determines if a recurring rule has a specific end

func (RepeaterConfiguration) NextScheduledAt

func (c RepeaterConfiguration) NextScheduledAt(repeat int) time.Time

NextScheduledAt returns the next Nth date a rule should occur. Note that things generates these ToDos as necessary.

type RepeaterDetailConfiguration

type RepeaterDetailConfiguration struct {
	Day     *int64        `json:"dy,omitempty"`
	Month   *int64        `json:"mo,omitempty"`
	Weekday *time.Weekday `json:"wd,omitempty"`
	MonthOf *int64        `json:"wdo,omitempty"`
}

RepeaterDetailConfiguration configures specifics of a repeater configuration.

type Setting

type Setting struct{}

Setting describes things settings 0|uuid|TEXT|0||1 1|logInterval|INTEGER|0||0 2|manualLogDate|REAL|0||0 3|groupTodayByParent|INTEGER|0||0

type Tag

type Tag struct {
	UUID         string
	Title        string
	ParentTagIDs []string
	ShortHand    string
}

Tag describes the aggregated state of an Tag 0|uuid|TEXT|0||1 1|title|TEXT|0||0 2|shortcut|TEXT|0||0 3|usedDate|REAL|0||0 4|parent|TEXT|0||0 5|index|INTEGER|0||0

type TagActionItem

type TagActionItem struct {
	Item
	P TagActionItemPayload `json:"p"`
}

TagActionItem describes an event on a tag

func (TagActionItem) UUID

func (t TagActionItem) UUID() string

UUID returns the UUID of the modified Tag

type TagActionItemPayload

type TagActionItemPayload struct {
	IX            *int            `json:"ix"`
	Title         *string         `json:"tt"`
	ShortHand     *string         `json:"sh"`
	ParentTagIDs  *[]string       `json:"pn"`
	ExtensionData json.RawMessage `json:"xx,omitempty"`
}

TagActionItemPayload describes the payload for modifying Areas

type Task

type Task struct {
	UUID             string
	CreationDate     time.Time
	ModificationDate *time.Time
	Status           TaskStatus
	Title            string
	Note             string
	ScheduledDate    *time.Time
	CompletionDate   *time.Time
	DeadlineDate     *time.Time
	Index            int
	AreaIDs          []string
	ParentTaskIDs    []string
	ActionGroupIDs   []string
	InTrash          bool
	Schedule         TaskSchedule
	Type             TaskType
	TodayIndex       int
	DueOrder         int
	AlarmTimeOffset  *int
	TagIDs           []string
	RecurrenceIDs    []string
	DelegateIDs      []string
}

Task describes a Task inside things. 0|uuid|TEXT|0||1 1|userModificationDate|REAL|0||0 2|creationDate|REAL|0||0 3|trashed|INTEGER|0||0 4|type|INTEGER|0||0 5|title|TEXT|0||0 6|notes|TEXT|0||0 7|dueDate|REAL|0||0 8|dueDateOffset|INTEGER|0||0 9|status|INTEGER|0||0 10|stopDate|REAL|0||0 11|start|INTEGER|0||0 12|startDate|REAL|0||0 13|index|INTEGER|0||0 14|todayIndex|INTEGER|0||0 15|area|TEXT|0||0 16|project|TEXT|0||0 17|repeatingTemplate|TEXT|0||0 18|delegate|TEXT|0||0 19|recurrenceRule|BLOB|0||0 20|instanceCreationStartDate|REAL|0||0 21|instanceCreationPaused|INTEGER|0||0 22|instanceCreationCount|INTEGER|0||0 23|afterCompletionReferenceDate|REAL|0||0 24|actionGroup|TEXT|0||0 25|untrashedLeafActionsCount|INTEGER|0||0 26|openUntrashedLeafActionsCount|INTEGER|0||0 27|checklistItemsCount|INTEGER|0||0 28|openChecklistItemsCount|INTEGER|0||0 29|startBucket|INTEGER|0||0 30|alarmTimeOffset|REAL|0||0 31|lastAlarmInteractionDate|REAL|0||0 32|todayIndexReferenceDate|REAL|0||0 33|nextInstanceStartDate|REAL|0||0 34|dueDateSuppressionDate|REAL|0||0

type TaskActionItem

type TaskActionItem struct {
	Item
	P TaskActionItemPayload `json:"p"`
}

TaskActionItem describes an event on a Task

func (TaskActionItem) UUID

func (t TaskActionItem) UUID() string

UUID returns the UUID of the modified Task

type TaskActionItemPayload

type TaskActionItemPayload struct {
	Index                     *int                   `json:"ix,omitempty"`
	CreationDate              *Timestamp             `json:"cd,omitempty"`
	ModificationDate          *Timestamp             `json:"md,omitempty"` // ok
	ScheduledDate             *Timestamp             `json:"sr,omitempty"`
	CompletionDate            *Timestamp             `json:"sp,omitempty"`
	DeadlineDate              *Timestamp             `json:"dd,omitempty"`  //
	TaskIR                    *Timestamp             `json:"tir,omitempty"` // hm, not sure what tir stands for
	Status                    *TaskStatus            `json:"ss,omitempty"`
	Type                      *TaskType              `json:"tp,omitempty"`
	Title                     *string                `json:"tt,omitempty"`
	Note                      json.RawMessage        `json:"nt,omitempty"`
	AreaIDs                   *[]string              `json:"ar,omitempty"`
	ParentTaskIDs             *[]string              `json:"pr,omitempty"`
	TagIDs                    []string               `json:"tg,omitempty"`
	InTrash                   *bool                  `json:"tr,omitempty"`
	TaskIndex                 *int                   `json:"ti,omitempty"`
	RecurrenceTaskIDs         *[]string              `json:"rt,omitempty"`
	Schedule                  *TaskSchedule          `json:"st,omitempty"`
	ActionGroupIDs            *[]string              `json:"agr,omitempty"`
	Repeater                  *RepeaterConfiguration `json:"rr,omitempty"`
	DueOrder                  *int                   `json:"do,omitempty"`
	Leavable                  *bool                  `json:"lt,omitempty"`
	IsCompletedByChildren     *bool                  `json:"icp,omitempty"`
	IsCompletedCount          *int                   `json:"icc,omitempty"`
	InstanceCreationStartDate *Timestamp             `json:"icsd,omitempty"`
	SubtaskBehavior           *int                   `json:"sb,omitempty"`
	DelegateIDs               *[]string              `json:"dl,omitempty"`
	LastActionItemID          *Timestamp             `json:"lai,omitempty"`
	ReminderDate              *Timestamp             `json:"rmd,omitempty"` // legacy API name: repeater migration date, not a reminder
	AlarmTimeOffset           *int                   `json:"ato,omitempty"`
	ActionRequiredDate        *Timestamp             `json:"acrd,omitempty"`
	DeadlineSuppression       *Timestamp             `json:"dds,omitempty"`
	ExtensionData             json.RawMessage        `json:"xx,omitempty"`
}

TaskActionItemPayload describes the payload for modifying Tasks, and also Projects, as projects are special kind of Tasks

type TaskReadPayload

type TaskReadPayload struct {
	TaskActionItemPayload
	// contains filtered or unexported fields
}

TaskReadPayload adds explicit-null tracking to the existing wire payload without changing its write representation. Unknown properties remain available in the original Item.P; this helper interprets supported fields.

func DecodeTaskReadPayload

func DecodeTaskReadPayload(raw json.RawMessage) (TaskReadPayload, error)

DecodeTaskReadPayload distinguishes an omitted property (preserve existing state) from an explicit null (clear a nullable property).

func (TaskReadPayload) ApplyNulls

func (p TaskReadPayload) ApplyNulls(task *Task)

ApplyNulls clears nullable fields after the ordinary non-nil payload fields have been applied. In particular, tir is a reference date and never changes ScheduledDate; only sr controls that field.

func (TaskReadPayload) ResolveNote

func (p TaskReadPayload) ResolveNote(current string) (string, error)

ResolveNote applies the note field to current using the read protocol's plain-text, full-text, delta, and explicit-null semantics.

type TaskSchedule

type TaskSchedule int

TaskSchedule describes when a task is scheduled

const (
	// TaskScheduleInbox indicates unprocessed tasks in the Inbox (st=0)
	TaskScheduleInbox TaskSchedule = 0
	// TaskScheduleAnytime indicates started tasks; displayed in Today when sr/tir
	// are set to today's date, or in Anytime when sr/tir are null (st=1)
	TaskScheduleAnytime TaskSchedule = 1
	// TaskScheduleSomeday indicates deferred tasks; displayed in Upcoming when
	// sr/tir have a future date, or in Someday when sr/tir are null (st=2)
	TaskScheduleSomeday TaskSchedule = 2

	// TaskScheduleToday is deprecated: use TaskScheduleAnytime with sr/tir dates.
	// The "st" field value 0 actually means Inbox, not Today.
	// Kept for backward compatibility.
	TaskScheduleToday = TaskScheduleInbox
)

func Schedule

func Schedule(val TaskSchedule) *TaskSchedule

Schedule returns a pointer to a TaskSchedule

func (TaskSchedule) String

func (i TaskSchedule) String() string

type TaskStatus

type TaskStatus int

TaskStatus describes if a thing is completed or not

const (
	// TaskStatusPending indicates a new task
	TaskStatusPending TaskStatus = iota
	// TaskStatusCompleted indicates a completed task
	TaskStatusCompleted TaskStatus = 3
	// TaskStatusCanceled indicates a canceled task
	TaskStatusCanceled TaskStatus = 2
)

func Status

func Status(val TaskStatus) *TaskStatus

Status returns a pointer to a TaskStatus

func (TaskStatus) String

func (i TaskStatus) String() string

type TaskType

type TaskType int

TaskType describes the type of a task entity

const (
	TaskTypeTask    TaskType = 0
	TaskTypeProject TaskType = 1
	TaskTypeHeading TaskType = 2
)

func TaskTypePtr

func TaskTypePtr(val TaskType) *TaskType

TaskTypePtr returns a pointer to a TaskType

type Timestamp

type Timestamp time.Time

Timestamp allows unix epochs represented as float or ints to be unmarshalled into time.Time objects

func Time

func Time(val time.Time) *Timestamp

Time returns a pointer to a Time. The zero time returns nil: its UnixNano is out of range and would marshal to a garbage 1754 date.

func (*Timestamp) Format

func (t *Timestamp) Format(layout string) string

Format returns a textual representation of the time value formatted according to layout

func (*Timestamp) MarshalJSON

func (t *Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON converts a timestamp into a fractional unix epoch (seconds with sub-second precision), matching the format used by the Things Cloud API (e.g. 1770713623.4716659).

func (*Timestamp) Time

func (t *Timestamp) Time() *time.Time

Time returns the underlying time.Time instance

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(bs []byte) error

UnmarshalJSON takes a unix epoch from float/ int and creates a time.Time instance, preserving sub-second precision.

type TombstoneActionItem

type TombstoneActionItem struct {
	Item
	P TombstoneActionItemPayload `json:"p"`
}

TombstoneActionItem describes a tombstone deletion event

func (TombstoneActionItem) UUID

func (t TombstoneActionItem) UUID() string

UUID returns the UUID of the TombstoneActionItem

type TombstoneActionItemPayload

type TombstoneActionItemPayload struct {
	DeletedObjectID string  `json:"dloid"`
	DeletionDate    float64 `json:"dld"`
}

TombstoneActionItemPayload describes the payload for tombstone deletion records

type UnsupportedTaskKindError

type UnsupportedTaskKindError struct {
	Kind        ItemKind
	ServerIndex int
}

UnsupportedTaskKindError means the task state would be incomplete if replay continued. ServerIndex is -1 when the source did not provide an index.

func (*UnsupportedTaskKindError) Error

func (e *UnsupportedTaskKindError) Error() string

type VerifyResponse

type VerifyResponse struct {
	SLAVersionAccepted string          `json:"SLA-version-accepted"`
	Issues             json.RawMessage `json:"issues"`
	Email              string          `json:"email"`
	MaildropEmail      string          `json:"maildrop-email"`
	Status             AccountStatus   `json:"status"`
	HistoryKey         string          `json:"history-key"`
}

VerifyResponse contains details about your account