todoist

package module
v1.0.0-beta.2 Latest Latest
Warning

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

 Go to latest Published: Jul 6, 2021 License: MIT Imports: 8 Imported by: 0

README

Todist API

A simple unofficial Todoist REST API Client

This is a work in progress and not ready for production usage yet.

Installing

Requires Go modules. You can go get the module and add it to your go.mod:

go get github.com/treelightsoftware/go-todoist

Usage

To get started, you should be familiar with how Todoist organizes its entities in their docs.

You will need to get the authentication token for the user. This can be done either through an oAuth flow OR you can pass it through the environment. This is a lsight nuance to this library, as most calls have a token parameter are the first for the functions. If you pass in an auth token AND leave that field blank, the call will automatically use the environment's passed in auth token. So, for example, to get a list of projects for a user, you could do the following:

import todo "github.com/treelightsoftware/go-todoist"

// this will get all of the projects for the user with that token; useful if you have multiple users on your integration
projects, err := todo.GetAllProjects("user_token")

Alternatively, if you are using this SDK in a project that involves only a single user (such as a CLI or local application), and you know the auth token ahead of time (such as from the integrations site), you can pass it into the environment:

TODOIST_AUTH_TOKEN=the_token ./your_app

This will set the config.AuthToken field at startup, and you would instead make your calls in either of the following ways:

import todo "github.com/treelightsoftware/go-todoist"

// explicitly grab it from the config
projects, err := todo.GetAllProjects(config.AuthToken)

// OR

// implicitly grab it from the config, filled in during the makeCall client function invocation
projects, err := todo.GetAllProjects("")

The pattern persists throughout.

Why pointers for the fields of the params?

The default values have meaning in the Todoist API. In otherwords, if you try to update a task and set the content, but not the description field, the description will default to "", so it will be set to blank without the user's intention. For further inspiration, see the excellent Stripe-Go library.

Contributing

Contributors are welcome. You should raise an issue or communicate with us prior to committing any significant effort to ensure that your desired changes are compatible with where we want this library to go. Read more in the CONTRIBUTING.md document. Make sure your tests pass (you will need to provide your own authentication token to get ideal coverage).

TODO

The following API end points are provided by v1 of the Todoist API. If it has an X, it's been implemented:

  • Projects
    • Get All Projects
    • Create a New Project
    • Get a Project
    • Update a Project
    • Delete a Project
    • Get All Collaborators
  • Sections
    • Get All Sections
    • Create a New Section
    • Get a Single Section
    • Update a Section
    • Delete a Section
  • Tasks
    • Get Active Tasks
    • Create a New Task
    • Get an Active Task
    • Update a Task
    • Close a Task
    • Reopen a Task
    • Delete a Task
  • Comments
    • Get All Comments
    • Create a Comment
    • Get a Comment
    • Update a Comment
    • Delete a Comment
  • Labels
    • Get All Labels
    • Create a New Label
    • Get a Label
    • Update a Label
    • Delete a Label
  • Webhooks
    • Add function that takes HTTP request, parses it, and returns relevant information to the user
Other TODOs
  • Implement code coverage with dummy token in CI/CD
  • Improve error checking; for example, if a task's DueDatetime is set, make sure it includes the time component
  • Provide better documentation on usage

Documentation

Index

Constants

View Source 
const (
	EndpointNameGetProjects   = "GetProjects"
	EndpointNameCreateProject = "CreateProject"
	EndpointNameDeleteProject = "DeleteProject"
	EndpointNameGetProject    = "GetProject"
	EndpointNameUpdateProject = "UpdateProject"

	EndpointNameGetAllActiveTasks = "GetTasks"
	EndpointNameCreateTask        = "CreateTask"
	EndpointNameGetTask           = "GetTask"
	EndpointNameDeleteTask        = "DeleteTask"
	EndpointNameUpdateTask        = "UpdateTask"
	EndpointNameCloseTask         = "CloseTask"
	EndpointNameReopenTask        = "ReopenTask"

	EndpointNameGetAllSections = "GetAllSections"
	EndpointNameGetSection     = "GetSection"
	EndpointNameCreateSection  = "CreateSection"
	EndpointNameUpdateSection  = "UpdateSection"
	EndpointNameDeleteSection  = "DeleteSection"

	EndpointNameGetAllLabels = "GetAllLabels"
	EndpointNameGetLabel     = "GetLabel"
	EndpointNameCreateLabel  = "CreateLabel"
	EndpointNameUpdateLabel  = "UpdateLabel"
	EndpointNameDeleteLabel  = "DeleteLabel"
)

Variables

This section is empty.

Functions

func Bool 

func Bool(in bool) *bool

func BoolValue 

func BoolValue(in *bool) bool

func CloseTask 

func CloseTask(token string, taskID int64) error

CloseTask closes a task. According to the docs, this will cause root tasks to be marked complete and moved to the history. https://developer.todoist.com/rest/v1/#close-a-task

func DeleteLabel 

func DeleteLabel(token string, labelID int64) error

DeleteLabel deletes a label. https://developer.todoist.com/rest/v1/#delete-a-label

func DeleteProject 

func DeleteProject(token string, projectID int64) error

DeleteProject deletes a project. https://developer.todoist.com/rest/v1/#delete-a-project

func DeleteSection 

func DeleteSection(token string, sectionID int64) error

DeleteSection deletes a section. https://developer.todoist.com/rest/v1/#delete-a-section

func DeleteTask 

func DeleteTask(token string, taskID int64) error

DeleteTask deletes a task. You probably want to close it instead? https://developer.todoist.com/rest/v1/#delete-a-task

func Int64 

func Int64(in int64) *int64

func Int64Value 

func Int64Value(in *int64) int64

func ReopenTask 

func ReopenTask(token string, taskID int64) error

ReopenTask reopens a closed task. https://developer.todoist.com/rest/v1/#reopen-a-task

func String 

func String(in string) *string

func StringValue 

func StringValue(in *string) string

Types

type Color 

type Color int64

the colors are standardized at https://developer.todoist.com/guides/#colors 

const (
	// ColorBerryRed is #b8256f
	ColorBerryRed Color = 30
	// ColorRed is #db4035
	ColorRed Color = 31
	// ColorOrange is #ff9933
	ColorOrange Color = 32
	// ColorYellow is #fad000
	ColorYellow Color = 33
	// ColorOliveGreen is #afb83b
	ColorOliveGreen Color = 34
	// ColorLimeGreen is #7ecc49
	ColorLimeGreen Color = 35
	// ColorGreen is #299438
	ColorGreen Color = 36
	// ColorMintGreen is #6accbc
	ColorMintGreen Color = 37
	// ColorTeal is #158fad
	ColorTeal Color = 38
	// ColorSkyBlue is #14aaf5
	ColorSkyBlue Color = 39
	// ColorLightBlue is #96c3eb
	ColorLightBlue Color = 40
	// ColorBlue is #4073ff
	ColorBlue Color = 41
	// ColorGrape is #884dff
	ColorGrape Color = 42
	// ColorViolet is #af38eb
	ColorViolet Color = 43
	// ColorLavender is #eb96eb
	ColorLavender Color = 44
	// ColorMagenta is #e05194
	ColorMagenta Color = 45
	// ColorSalmon is #ff8d85
	ColorSalmon Color = 46
	// ColorCharcoal is #808080
	ColorCharcoal Color = 47
	// ColorGrey is #b8b8b8
	ColorGrey Color = 48
	// ColorTaupe is #ccac93
	ColorTaupe Color = 49
)

type Configuration 

type Configuration struct {
	AuthToken string // should be set if, and only if, you are using this for a single user
}

type Label 

type Label struct {
	ID       int64  `json:"id" db:"id"`
	Name     string `json:"name" db:"name"`
	Color    int64  `json:"color" db:"color"`
	Order    int64  `json:"order" db:"order"`
	Favorite bool   `json:"favorite" db:"favorite"`
}

Label represent a label that can be assigned to a task

func CreateLabel 

func CreateLabel(token string, input *LabelParams) (*Label, error)

CreateLabel creates a label and requires at least a name. https://developer.todoist.com/rest/v1/#create-a-new-label

func GetAllLabels 

func GetAllLabels(token string) ([]Label, error)

GetAllLabels returns all of the labels for a user's token. https://developer.todoist.com/rest/v1/#get-all-labels

func GetLabel 

func GetLabel(token string, labelID int64) (*Label, error)

GetLabel gets a single label. https://developer.todoist.com/rest/v1/#get-a-label

func UpdateLabel 

func UpdateLabel(token string, labelID int64, input *LabelParams) (*Label, error)

UpdateLabel updates a label. https://developer.todoist.com/rest/v1/#update-a-label

type LabelParams 

type LabelParams struct {
	Name     string `json:"name" db:"name"`
	Color    *int64 `json:"color" db:"color"`
	Order    *int64 `json:"order" db:"order"`
	Favorite *bool  `json:"favorite" db:"favorite"`
}

LabelParams are used when creating or updating a label

type Priority 

type Priority int
const (
	PriorityNormal Priority = 1
	PriorityHigh   Priority = 2
	PriorityHigher Priority = 3
	PriorityUrgent Priority = 4
)

type Project 

type Project struct {
	ID           int64  `json:"id,omitempty" db:"id"`
	Name         string `json:"name" db:"name"`
	CommentCount int64  `json:"comment_count" db:"comment_count"`
	Order        int64  `json:"order" db:"order"`
	Color        Color  `json:"color" db:"color"`
	Shared       bool   `json:"shared" db:"shared"`
	SyncID       int64  `json:"sync_id" db:"sync_id"`
	Favorite     bool   `json:"favorite" db:"favorite"`
	InboxProject bool   `json:"inbox_project" db:"inbox_project"`
	URL          string `json:"url" db:"url"`
	TeamInbox    bool   `json:"team_inbox" db:"team_inbox"`
	ParentID     int64  `json:"parent_id" db:"parent_id"`
}

Project represents a project at Todoist, which holds the tasks, etc. Although the SKD doesn't interact with a DB, we provide an opinionated db name for the field that is the same as the JSON

func CreateProject 

func CreateProject(token string, input *ProjectParams) (*Project, error)

CreateProject creates a new project for the user. Tasks belong to projects and require, at a minimum, a name. https://developer.todoist.com/rest/v1/#create-a-new-project

func CreateTestProject 

func CreateTestProject(token string) (*Project, error)

CreateTestProject creates a simple test project to be used in tests

func GetAllProjects 

func GetAllProjects(token string) ([]Project, error)

GetAllProjects returns all of the project for a user's token. https://developer.todoist.com/rest/v1/#get-all-projects

func GetProject 

func GetProject(token string, projectID int64) (*Project, error)

GetProject gets a single project by its id. https://developer.todoist.com/rest/v1/#get-a-project

func UpdateProject 

func UpdateProject(token string, projectID int64, params *ProjectParams) (*Project, error)

UpdateProject updates a project. Currently, only name, color, and favorite are supported. https://developer.todoist.com/rest/v1/#update-a-project

type ProjectParams 

type ProjectParams struct {
	Name     *string `json:"name,omitempty" db:"name"`
	ParentID *int64  `json:"parent_id,omitempty" db:"parent_id"`
	Color    Color   `json:"color,omitempty" db:"color"`
	Favorite *bool   `json:"favorite,omitempty" db:"favorite"`
}

ProjectParams are the fields set during creating or updating a project

type Section 

type Section struct {
	ID        int64  `json:"id" db:"id"`
	ProjectID int64  `json:"project_id" db:"project_id"`
	Name      string `json:"name" db:"name"`
	Order     int64  `json:"order" db:"order"`
}

Section divides a project into logical sections

func CreateSection 

func CreateSection(token string, input *SectionParams) (*Section, error)

CreateSection creates a section and requires at least a name and project_id. https://developer.todoist.com/rest/v1/#create-a-new-section

func GetAllSections 

func GetAllSections(token string, projectID int64) ([]Section, error)

GetAllSections returns all of the sections for a user's token. If provided a non-zero project ID, it will get only sections for that project. https://developer.todoist.com/rest/v1/#get-all-sections

func GetSection 

func GetSection(token string, sectionID int64) (*Section, error)

GetSection gets a single section. https://developer.todoist.com/rest/v1/#get-a-single-section

func UpdateSection 

func UpdateSection(token string, sectionID int64, input *SectionParams) (*Section, error)

UpdateSection updates a section. Currently, only the name may change. https://developer.todoist.com/rest/v1/#update-a-section

type SectionParams 

type SectionParams struct {
	ProjectID *int64 `json:"project_id" db:"project_id"`
	Name      string `json:"name" db:"name"`
	Order     *int64 `json:"order" db:"order"`
}

SectionParams are the fields used when creating or editing sections

type Task 

type Task struct {
	ID           int64       `json:"id" db:"id"`
	ProjectID    int64       `json:"project_id" db:"project_id"`
	SectionID    int64       `json:"section_id" db:"section_id"`
	Content      string      `json:"content" db:"content"`
	Description  string      `json:"description" db:"description"`
	Completed    bool        `json:"completed" db:"completed"`
	LabelIDs     []int64     `json:"label_ids" db:"label_ids"`
	ParentID     int64       `json:"parent_id" db:"parent_id"`
	Order        int64       `json:"order" db:"order"`
	Priority     Priority    `json:"priority" db:"priority"`
	Due          TaskDueInfo `json:"due" db:"due"`
	URL          string      `json:"url" db:"url"`
	CommentCount int64       `json:"comment_count" db:"comment_count"`
	Assignee     int64       `json:"assignee" db:"assignee"`
	Assigner     int64       `json:"assigner" db:"assigner"`
}

Task represents a single todo item to track

func CreateTask 

func CreateTask(token string, input *TaskParams) (*Task, error)

CreateTask creates a returns a new task. The only required field is the content field. https://developer.todoist.com/rest/v1/#create-a-new-task

func GetActiveTask 

func GetActiveTask(token string, taskID int64) (*Task, error)

GetActiveTask gets a single task by its id. https://developer.todoist.com/rest/v1/#get-an-active-task

func GetActiveTasks 

func GetActiveTasks(token string) ([]Task, error)

GetActiveTasks gets the active tasks for a user. https://developer.todoist.com/rest/v1/#get-active-tasks

func UpdateTask 

func UpdateTask(token string, taskID int64, newData *TaskParams) (*Task, error)

UpdateTask updates a task. https://developer.todoist.com/rest/v1/#update-a-task

type TaskDueInfo 

type TaskDueInfo struct {
	Date      string `json:"date" db:"date"`
	Datetime  string `json:"datetime" db:"datetime"`
	Recurring bool   `json:"recurring" db:"recurring"`
	String    string `json:"string" db:"string"`
	Timezone  string `json:"timezone" db:"timezone"`
}

TaskDueInfo is the date/time information for a task

type TaskParams 

type TaskParams struct {
	ProjectID    *int64   `json:"project_id,omitempty" db:"project_id"`
	SectionID    *int64   `json:"section_id,omitempty" db:"section_id"`
	Content      *string  `json:"content,omitempty" db:"content"`
	Description  *string  `json:"description,omitempty" db:"description"`
	Completed    *bool    `json:"completed,omitempty" db:"completed"`
	LabelIDs     *[]int64 `json:"label_ids,omitempty" db:"label_ids"`
	ParentID     *int64   `json:"parent_id,omitempty" db:"parent_id"`
	Order        *int64   `json:"order,omitempty" db:"order"`
	Priority     Priority `json:"priority,omitempty" db:"priority"`
	URL          *string  `json:"url,omitempty" db:"url"`
	CommentCount *int64   `json:"comment_count,omitempty" db:"comment_count"`
	Assignee     *int64   `json:"assignee,omitempty" db:"assignee"`
	Assigner     *int64   `json:"assigner,omitempty" db:"assigner"`

	// we lift the following up for the update and create calls
	DueLang     *string `json:"due_lang" db:"due_lang"`
	DueString   *string `json:"due_string" db:"due_string"`
	DueDate     *string `json:"due_date" db:"due_date"`
	DueDatetime *string `json:"due_datetime" db:"due_datetime"`
}

TaskParams are the fields you can set when creating or updating

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.