todoist

README

= go-todoist

image:https://godoc.org/github.com/mhutter/go-todoist?status.svg[link="https://godoc.org/github.com/mhutter/go-todoist"]
image:https://circleci.com/gh/mhutter/go-todoist.svg?style=svg[link="https://circleci.com/gh/mhutter/go-todoist"]

https://golang.org[Go] client library for the https://todoist.com/r/manuel_bvrsbr[Todoist] Sync API v8.

CAUTION: This library is currently under development! See the https://github.com/mhutter/go-todoist/tree/develop[develop branch] for progress!


== Features

* Authentication via API token
* Fetch Projects and Tasks


=== Planned features

* Create Projects and Tasks
* Support for REST API?


== Requirements

* Go >= 1.13
* A https://todoist.com/r/manuel_bvrsbr[Todoist] account


== Installation

Go get it!

    go get github.com/mhutter/go-todoist


== API

See the https://gowalker.org/github.com/mhutter/go-todoist[GoDoc documentation] for detailed documentation.

For technical background see the https://developer.todoist.com/sync/v8/[Sync API documentation].

== Examples

Basic example
[source,go]
----
c := todoist.NewClient(apiToken, nil, todoist.ResourceProjects)
c.Sync()
openProjects := c.Projects()
----

For a more complete example see the `examples/` folder.

== License

MIT (see link:LICENSE[LICENSE])

---
> https://hutter.io/[Manuel Hutter] -
> GitHub https://github.com/mhutter[@mhutter] -
> Twitter https://twitter.com/dratir[@dratir]

Documentation

Overview

Package todoist implements a client for the Todoist API.

At this time, only the Sync API (https://developer.todoist.com/sync/v8/) is supported. This mainly means that it is only possible to fetch open and non-deleted resources.

Index

• Constants
• type DueDate
• type Item
• type Project
• type Resource
• type ResourceList
  • func (rl ResourceList) String() string
• type SyncClient
  • func NewSyncClient(token string, httpClient *http.Client, resources ...Resource) *SyncClient
  • func (c *SyncClient) Item(id int) *Item
  • func (c *SyncClient) Items() []Item
  • func (c *SyncClient) Project(id int) *Project
  • func (c *SyncClient) Projects() []Project
  • func (c *SyncClient) Sync() error
• type SyncResponse

Constants

const (
	ResourceAll                  = Resource("all")
	ResourceCollaborators        = Resource("collaborators")
	ResourceFilters              = Resource("filters")
	ResourceItems                = Resource("items")
	ResourceLabels               = Resource("labels")
	ResourceLiveNotifications    = Resource("live_notifications")
	ResourceLocations            = Resource("locations")
	ResourceNotes                = Resource("notes")
	ResourceNotificationSettings = Resource("notification_settings")
	ResourceProjects             = Resource("projects")
	ResourceReminders            = Resource("reminders")
	ResourceSections             = Resource("sections")
	ResourceUser                 = Resource("user")
	ResourceUserSettings         = Resource("user_settings")
)

Resource Types that are exposed by the Sync API

const (
	// SyncAPIURL is the base URL all Sync API requests go to
	SyncAPIURL = "https://api.todoist.com/sync/v8/sync"
)

Types

type DueDate

type DueDate struct {
	Date        string
	Timezone    string
	String      string
	Lang        string
	IsRecurring bool
}

DueDate is todoist's representation of a due date. See https://developer.todoist.com/sync/v8/#due-dates-with-time-and-fixed-timezone

type Item

type Item struct {
	ID             int     `json:"id,omitempty"`
	UserID         int     `json:"user_id,omitempty"`
	ProjectID      int     `json:"project_id,omitempty"`
	Content        string  `json:"content,omitempty"`
	Priority       int     `json:"priority,omitempty"`
	Due            DueDate `json:"due,omitempty"`
	ParentID       int     `json:"parent_id,omitempty"`
	ChildOrder     int     `json:"child_order,omitempty"`
	SectionID      int     `json:"section_id,omitempty"`
	DayOrder       int     `json:"day_order,omitempty"`
	Collapsed      int     `json:"collapsed,omitempty"`
	Children       []int   `json:"children,omitempty"`
	Labels         []int   `json:"labels,omitempty"`
	AssignedByUID  int     `json:"assigned_by_uid,omitempty"`
	ResponsibleUID int     `json:"responsible_uid,omitempty"`
	Checked        int     `json:"checked,omitempty"`
	InHistory      int     `json:"in_history,omitempty"`
	IsDeleted      int     `json:"is_deleted,omitempty"`
	SyncID         int     `json:"sync_id,omitempty"`
	DateCompleted  string  `json:"date_completed,omitempty"`
	DateAdded      string  `json:"date_added,omitempty"`
}

Item represents a Todoist task on the Sync API. See https://developer.todoist.com/sync/v8/#items

type Project

type Project struct {
	ID           int    `json:"id,omitempty"`
	Name         string `json:"name,omitempty"`
	Color        int    `json:"color,omitempty"`
	ParentID     int    `json:"parent_id,omitempty"`
	ChildOrder   int    `json:"child_order,omitempty"`
	Collapsed    int    `json:"collapsed,omitempty"`
	Shared       bool   `json:"shared,omitempty"`
	IsDeleted    int    `json:"is_deleted,omitempty"`
	IsArchived   int    `json:"is_archived,omitempty"`
	IsFavorite   int    `json:"is_favorite,omitempty"`
	InboxProject bool   `json:"inbox_project,omitempty"`
	TeamInbox    bool   `json:"team_inbox,omitempty"`
}

Project represents a Todoist Project.

type Resource

type Resource string

Resource identifies a resource type as defined by the Sync API. See: https://developer.todoist.com/sync/v8/#read-resources

type ResourceList

type ResourceList []Resource

ResourceList is a list of resources.

func (ResourceList) String

func (rl ResourceList) String() string

type SyncClient

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

SyncClient manages the communication with the Todoist Sync API v8 (https://developer.todoist.com/sync/v8/).

func NewSyncClient

func NewSyncClient(token string, httpClient *http.Client, resources ...Resource) *SyncClient

NewSyncClient returns a new Todoist Sync API client. token is an API token that can be obtained from the ("Settings" -> "Integrations") page (https://todoist.com/prefs/integrations). If a nil httpClient is passed, then http.DefaultClient is used instead. As the last argument, a list of resources to be managed by this client must be passed. At least one resource must be passed.

func (*SyncClient) Item

func (c *SyncClient) Item(id int) *Item

Item returns a project by its ID, or nil if the ID cannot be found.

func (*SyncClient) Items

func (c *SyncClient) Items() []Item

Items returns all items

func (*SyncClient) Project

func (c *SyncClient) Project(id int) *Project

Project returns a project by its ID, or nil if the ID cannot be found.

func (*SyncClient) Projects

func (c *SyncClient) Projects() []Project

Projects returns all projects

func (*SyncClient) Sync

func (c *SyncClient) Sync() error

Sync does an incremental sync (or full sync if required) for the configured Todoist resource types.

type SyncResponse

type SyncResponse struct {
	SyncToken     string            `json:"sync_token"`
	TempIDMapping map[string]string `json:"temp_id_mapping"`
	FullSync      bool              `json:"full_sync"`

	// Resources
	Projects []Project `json:"projects,omitempty"`
	Items    []Item    `json:"items,omitempty"`
}

SyncResponse represents a JSON response as sent by the Todoist Sync API