wl

README

wl

Unofficial Wunderlist API client library and CLI, written in golang.

Copyright © 2014-2016, Robert Dimsdale. Licensed under the MIT License.

Why?

• The library provides access to all of the endpoints documented in the official API docs, plus additional useful methods like inbox and delete-all-tasks.
• The CLI is written in golang, which results in an statically-compiled CLI.

Library

Install the library with:

go get gopkg.in/robdimsdale/wl.v1

or

go get github.com/robdimsdale/wl

Usage

Create an instance of wl.Client using e.g. oauth.NewClient() as follows:

import (
  "fmt"

  "github.com/robdimsdale/wl"
  "github.com/robdimsdale/wl/logger"
  "github.com/robdimsdale/wl/oauth"
)

func main() {
  client := oauth.NewClient(
    "my_access_token",
    "my_client_id",
    wl.APIURL,
    logger.NewLogger(logger.INFO),
  )

  // Ignore error
  inbox, _ := client.Inbox()
  fmt.Printf("Inbox: %v\n", inbox)
}

Supported Golang versions

The code is tested against the latest patch versions of the most recent minor and the previous minor versions of golang.

Branches

The develop branch is where active development takes place; it is not guaranteed that any given commit will be stable.

The master branch points to a stable commit. All tests should pass.

CLI Binary

A CLI is provided with support for some utility functions (e.g. list all tasks, delete all folders).

Installation

Binaries are available on the releases page for various operating systems and architectures.

Download the binary and place in the PATH.

OSX

A homebrew tap is available; install the binary with:

brew tap robdimsdale/tap
brew install wl

Usage

Access token and client id are required. Provide them via flags (--accessToken and --clientID) or with environment variables (WL_ACCESS_TOKEN or WL_CLIENT_ID)

$ wl inbox --accessToken my_access_token --clientID my_client_id
id: 123456789
title: inbox
created_at: 2014-08-29T19:45:34.98Z
list_type: inbox
revision: 53538
type: list
public: false

$ WL_ACCESS_TOKEN=my_access_token WL_CLIENT_ID=my_client_id wl create-task --list-id 123456789 --title "some new title"
id: 987654321
[...]
list_id: 123456789
title: some new title
completed: false

Development

Go dependencies

The library has no dependencies.

The CLI binary vendors its dependencies in the vendor directory according to the golang specification.

Running the tests

Running the tests will require ginkgo.

Execute the unit tests with:

./scripts/unit-tests

The integration tests require the following environment variables to be set: WL_CLIENT_ID and WL_ACCESS_TOKEN. Values for these are obtained via the method documented at https://developer.wunderlist.com/documentation/concepts/authorization.

In the cloned directory run the following command:

WL_CLIENT_ID=my_client_id WL_ACCESS_TOKEN=my_access_token ./scripts/integration_tests

Project administration

Tracker

• Roadmap: Pivotal Tracker

CI

• CI is performed using Concourse: https://concourse.robdimsdale.com/pipelines/wl

Documentation

Overview

Package wl provides a client to the Wunderlist API.

For more information on the API, see https://developer.wunderlist.com/documentation

Index

• Constants
• type Client
• type File
• type FilePreview
• type Folder
• type FolderRevision
• type List
• type ListTaskCount
• type Membership
• type Note
• type Position
• type Reminder
• type Root
• type Subtask
• type Task
• type TaskComment
• type Upload
• type User
• type Webhook

Constants

const (
	// APIURL is the default URL for Wunderlist API.
	APIURL = "https://a.wunderlist.com/api/v1"
)

Types

type Client

type Client interface {
	User() (User, error)
	UpdateUser(user User) (User, error)
	Users() ([]User, error)
	UsersForListID(listID uint) ([]User, error)

	Lists() ([]List, error)
	List(listID uint) (List, error)
	CreateList(title string) (List, error)
	UpdateList(list List) (List, error)
	DeleteList(list List) error
	DeleteAllLists() error
	Inbox() (List, error)

	Notes() ([]Note, error)
	NotesForListID(listID uint) ([]Note, error)
	NotesForTaskID(taskID uint) ([]Note, error)
	Note(noteID uint) (Note, error)
	CreateNote(content string, taskID uint) (Note, error)
	UpdateNote(note Note) (Note, error)
	DeleteNote(note Note) error

	Tasks() ([]Task, error)
	CompletedTasks(completed bool) ([]Task, error)
	TasksForListID(listID uint) ([]Task, error)
	CompletedTasksForListID(listID uint, completed bool) ([]Task, error)
	Task(taskID uint) (Task, error)
	CreateTask(
		title string,
		listID uint,
		assigneeID uint,
		completed bool,
		recurrenceType string,
		recurrenceCount uint,
		dueDate time.Time,
		starred bool,
	) (Task, error)
	UpdateTask(task Task) (Task, error)
	DeleteTask(task Task) error
	DeleteAllTasks() error

	Subtasks() ([]Subtask, error)
	SubtasksForListID(listID uint) ([]Subtask, error)
	SubtasksForTaskID(taskID uint) ([]Subtask, error)
	CompletedSubtasks(completed bool) ([]Subtask, error)
	CompletedSubtasksForListID(listID uint, completed bool) ([]Subtask, error)
	CompletedSubtasksForTaskID(taskID uint, completed bool) ([]Subtask, error)
	Subtask(subtaskID uint) (Subtask, error)
	CreateSubtask(
		title string,
		taskID uint,
		completed bool,
	) (Subtask, error)
	UpdateSubtask(subtask Subtask) (Subtask, error)
	DeleteSubtask(subtask Subtask) error

	Reminders() ([]Reminder, error)
	RemindersForListID(listID uint) ([]Reminder, error)
	RemindersForTaskID(taskID uint) ([]Reminder, error)
	Reminder(reminderID uint) (Reminder, error)
	CreateReminder(
		date string,
		taskID uint,
		createdByDeviceUdid string,
	) (Reminder, error)
	UpdateReminder(reminder Reminder) (Reminder, error)
	DeleteReminder(reminder Reminder) error

	ListPositions() ([]Position, error)
	ListPosition(listPositionID uint) (Position, error)
	UpdateListPosition(listPosition Position) (Position, error)

	TaskPositions() ([]Position, error)
	TaskPositionsForListID(listID uint) ([]Position, error)
	TaskPosition(taskPositionID uint) (Position, error)
	UpdateTaskPosition(taskPosition Position) (Position, error)

	SubtaskPositions() ([]Position, error)
	SubtaskPositionsForListID(listID uint) ([]Position, error)
	SubtaskPositionsForTaskID(taskID uint) ([]Position, error)
	SubtaskPosition(subtaskPositionID uint) (Position, error)
	UpdateSubtaskPosition(subtaskPosition Position) (Position, error)

	Memberships() ([]Membership, error)
	MembershipsForListID(listID uint) ([]Membership, error)
	Membership(membershipID uint) (Membership, error)
	AddMemberToListViaUserID(userID uint, listID uint, muted bool) (Membership, error)
	AddMemberToListViaEmailAddress(emailAddress string, listID uint, muted bool) (Membership, error)
	RejectInvite(membership Membership) error
	RemoveMemberFromList(membership Membership) error
	AcceptMember(membership Membership) (Membership, error)

	TaskComments() ([]TaskComment, error)
	TaskCommentsForListID(listID uint) ([]TaskComment, error)
	TaskCommentsForTaskID(taskID uint) ([]TaskComment, error)
	CreateTaskComment(text string, taskID uint) (TaskComment, error)
	TaskComment(taskCommentID uint) (TaskComment, error)
	DeleteTaskComment(taskComment TaskComment) error

	AvatarURL(userID uint, size int, fallback bool) (string, error)

	Webhooks() ([]Webhook, error)
	WebhooksForListID(listID uint) ([]Webhook, error)
	Webhook(webhookID uint) (Webhook, error)
	CreateWebhook(listID uint, url string, processorType string, configuration string) (Webhook, error)
	DeleteWebhook(webhook Webhook) error

	Folders() ([]Folder, error)
	CreateFolder(title string, listIDs []uint) (Folder, error)
	Folder(folderID uint) (Folder, error)
	UpdateFolder(folder Folder) (Folder, error)
	DeleteFolder(folder Folder) error
	FolderRevisions() ([]FolderRevision, error)
	DeleteAllFolders() error

	UploadFile(
		localFilePath string,
		remoteFileName string,
		contentType string,
		md5sum string,
	) (Upload, error)

	Files() ([]File, error)
	FilesForTaskID(taskID uint) ([]File, error)
	FilesForListID(listID uint) ([]File, error)
	File(fileID uint) (File, error)
	CreateFile(uploadID uint, taskID uint) (File, error)
	DestroyFile(file File) error
	FilePreview(fileID uint, platform string, size string) (FilePreview, error)

	Root() (Root, error)
}

Client represents the methods that the API supports.

type File

type File struct {
	ID             uint      `json:"id" yaml:"id"`
	URL            string    `json:"url" yaml:"url"`
	TaskID         uint      `json:"task_id" yaml:"task_id"`
	ListID         uint      `json:"list_id" yaml:"list_id"`
	UserID         uint      `json:"user_id" yaml:"user_id"`
	FileName       string    `json:"file_name" yaml:"file_name"`
	ContentType    string    `json:"content_type" yaml:"content_type"`
	FileSize       int       `json:"file_size" yaml:"file_size"`
	LocalCreatedAt time.Time `json:"local_created_at" yaml:"local_created_at"`
	CreatedAt      time.Time `json:"created_at" yaml:"created_at"`
	UpdatedAt      time.Time `json:"updated_at" yaml:"updated_at"`
	Type           string    `json:"type" yaml:"type"`
	Revision       uint      `json:"revision" yaml:"revision"`
}

File contains the information about an uploaded file. See also Upload.

type FilePreview

type FilePreview struct {
	URL       string    `json:"url" yaml:"url"`
	Size      string    `json:"size" yaml:"size"`
	ExpiresAt time.Time `json:"expires_at" yaml:"expires_at"`
}

FilePreview contains the information about an image thumbnail

type Folder

type Folder struct {
	ID                 uint      `json:"id" yaml:"id"`
	Title              string    `json:"title" yaml:"title"`
	ListIDs            []uint    `json:"list_ids" yaml:"list_ids"`
	CreatedAt          time.Time `json:"created_at" yaml:"created_at"`
	CreatedByRequestID string    `json:"created_by_request_id" yaml:"created_by_request_id"`
	UpdatedAt          time.Time `json:"updated_at" yaml:"updated_at"`
	TypeString         string    `json:"type" yaml:"type"`
	Revision           uint      `json:"revision" yaml:"revision"`
}

Folder contains information about a folder. A list may or may not belong to a folder.

type FolderRevision

type FolderRevision struct {
	ID         uint   `json:"id" yaml:"id"`
	TypeString string `json:"type" yaml:"type"`
	Revision   uint   `json:"revision" yaml:"revision"`
}

FolderRevision contains information about the revision of folder.

type List

type List struct {
	ID         uint      `json:"id" yaml:"id"`
	Title      string    `json:"title" yaml:"title"`
	CreatedAt  time.Time `json:"created_at" yaml:"created_at"`
	ListType   string    `json:"list_type" yaml:"list_type"`
	Revision   uint      `json:"revision" yaml:"revision"`
	TypeString string    `json:"type" yaml:"type"`
	Public     bool      `json:"public" yaml:"public"`
}

List contains information about a List.

type ListTaskCount

type ListTaskCount struct {
	ID               uint   `json:"id" yaml:"id"`
	CompletedCount   uint   `json:"completed_count" yaml:"completed_count"`
	UncompletedCount uint   `json:"uncompleted_count" yaml:"uncompleted_count"`
	TypeString       string `json:"type" yaml:"type"`
}

ListTaskCount contains information about the number and type of tasks a List contains.

type Membership

type Membership struct {
	ID       uint   `json:"id" yaml:"id"`
	UserID   uint   `json:"user_id" yaml:"user_id"`
	ListID   uint   `json:"list_id" yaml:"list_id"`
	State    string `json:"state" yaml:"state"`
	Owner    bool   `json:"owner" yaml:"owner"`
	Muted    bool   `json:"muted" yaml:"muted"`
	Revision uint   `json:"revision" yaml:"revision"`
}

Membership joins Users and Lists.

type Note

type Note struct {
	ID        uint      `json:"id" yaml:"id"`
	TaskID    uint      `json:"task_id" yaml:"task_id"`
	Content   string    `json:"content" yaml:"content"`
	CreatedAt time.Time `json:"created_at" yaml:"created_at"`
	UpdatedAt time.Time `json:"updated_at" yaml:"updated_at"`
	Revision  uint      `json:"revision" yaml:"revision"`
}

Note represents the information about a note. Notes are large text blobs, and are children of tasks.

type Position

type Position struct {
	ID       uint   `json:"id" yaml:"id"`
	Values   []uint `json:"values" yaml:"values"`
	Revision uint   `json:"revision" yaml:"revision"`
}

Position contains an ordered list of IDs of Lists, Tasks or Subtasks.

type Reminder

type Reminder struct {
	ID        uint      `json:"id" yaml:"id"`
	Date      string    `json:"date" yaml:"date"`
	TaskID    uint      `json:"task_id" yaml:"task_id"`
	Revision  uint      `json:"revision" yaml:"revision"`
	CreatedAt time.Time `json:"created_at" yaml:"created_at"`
	UpdatedAt time.Time `json:"updated_at" yaml:"updated_at"`
}

Reminder contains information about a task reminder.

type Root

type Root struct {
	ID       uint `json:"id" yaml:"id"`
	Revision uint `json:"revision" yaml:"revision"`
	UserID   uint `json:"user_id" yaml:"user_id"`
}

Root contains information about the root of the object hierarchy.

type Subtask

type Subtask struct {
	ID            uint      `json:"id" yaml:"id"`
	TaskID        uint      `json:"task_id" yaml:"task_id"`
	CreatedAt     time.Time `json:"created_at" yaml:"created_at"`
	CreatedByID   uint      `json:"created_by_id" yaml:"created_by_id"`
	Revision      uint      `json:"revision" yaml:"revision"`
	Title         string    `json:"title" yaml:"title"`
	Completed     bool      `json:"completed" yaml:"completed"`
	CompletedAt   time.Time `json:"completed_at" yaml:"completed_at"`
	CompletedByID uint      `json:"completed_by" yaml:"completed_by"`
}

Subtask contains information about a subtask. Subtasks are children of tasks.

type Task

type Task struct {
	ID              uint      `json:"id" yaml:"id"`
	AssigneeID      uint      `json:"assignee_id" yaml:"assignee_id"`
	AssignerID      uint      `json:"assigner_id" yaml:"assigner_id"`
	CreatedAt       time.Time `json:"created_at" yaml:"created_at"`
	CreatedByID     uint      `json:"created_by_id" yaml:"created_by_id"`
	DueDate         time.Time `json:"due_date" yaml:"due_date"`
	ListID          uint      `json:"list_id" yaml:"list_id"`
	Revision        uint      `json:"revision" yaml:"revision"`
	Starred         bool      `json:"starred" yaml:"starred"`
	Title           string    `json:"title" yaml:"title"`
	Completed       bool      `json:"completed" yaml:"completed"`
	CompletedAt     time.Time `json:"completed_at" yaml:"completed_at"`
	CompletedByID   uint      `json:"completed_by" yaml:"completed_by"`
	RecurrenceType  string    `json:"recurrence_type" yaml:"recurrence_type"`
	RecurrenceCount uint      `json:"recurrence_count" yaml:"recurrence_count"`
}

Task contains information about tasks. Tasks are children of lists.

type TaskComment

type TaskComment struct {
	ID        uint      `json:"id" yaml:"id"`
	TaskID    uint      `json:"task_id" yaml:"task_id"`
	Revision  uint      `json:"revision" yaml:"revision"`
	Text      string    `json:"text" yaml:"text"`
	CreatedAt time.Time `json:"created_at" yaml:"created_at"`
}

TaskComment represents information about a comment on a Task.

type Upload

type Upload struct {
	ID     uint   `json:"id" yaml:"id"`
	UserID uint   `json:"user_id" yaml:"user_id"`
	State  string `json:"state" yaml:"state"`
}

Upload contains information about uploads. Uploads represent uploaded files.

type User

type User struct {
	ID        uint      `json:"id" yaml:"id"`
	Name      string    `json:"name" yaml:"name"`
	Email     string    `json:"email" yaml:"email"`
	CreatedAt time.Time `json:"created_at" yaml:"created_at"`
	UpdatedAt time.Time `json:"updated_at" yaml:"updated_at"`
	Revision  uint      `json:"revision" yaml:"revision"`
}

User contains information about a User.

type Webhook

type Webhook struct {
	ID             uint      `json:"id" yaml:"id"`
	ListID         uint      `json:"list_id" yaml:"list_id"`
	MembershipID   uint      `json:"membership_id" yaml:"membership_id"`
	MembershipType string    `json:"membership_type" yaml:"membership_type"`
	URL            string    `json:"url" yaml:"url"`
	ProcessorType  string    `json:"processor_type" yaml:"processor_type"`
	Configuration  string    `json:"configuration" yaml:"configuration"`
	CreatedAt      time.Time `json:"created_at" yaml:"created_at"`
	UpdatedAt      time.Time `json:"updated_at" yaml:"updated_at"`
}

Webhook contains information about webhooks. A webhook sends notifications when a list is updated.