thingscloud

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2017 License: MIT Imports: 9 Imported by: 0

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.

wercker status

TODO

  • Verify Credentials
  • Account Management
    • Signup/ Confirmation
    • Change Password
    • Account Deletion
  • History management
    • List Histories
    • Create History
    • Delete History
    • Sync History
    • Item Management
      • read items
      • recurring tasks
      • write items
    • State aggregation
      • InMemory
      • Persistent

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

Examples

Constants

View Source 
const (
	// APIEndpoint is the public culturedcode https endpoint
	APIEndpoint = "https://cloud.culturedcode.com/version/1"
)
View Source 
const ThingsUserAgent = "ThingsMac/30003505mas"

ThingsUserAgent is the http user-agent header set by things for mac Version 3.0.3 (30003505)

Variables

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

Functions

This section is empty.

Types

type AccountService 

type AccountService service

AccountService allows account specific interaction with thingscloud

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 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"`
}

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

	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) 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 History 

type History struct {
	ID                  string
	Client              *Client
	LatestServerIndex   int
	LatestSchemaVersion 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, 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"`
}

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"
	// ItemKindTask identifies a Task or Subtask
	ItemKindTask ItemKind = "Task3"
	// ItemKindArea identifies an Area
	ItemKindArea ItemKind = "Area2"
	// ItemKindSettings  identifies a setting
	ItemKindSettings ItemKind = "Settings3"
	// ItemKindTag identifies a Tag
	ItemKindTag ItemKind = "Tag3"
)

type ItemsOptions 

type ItemsOptions struct {
	StartIndex int
}

ItemsOptions allows a client to pickup changes from a specific index

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"`
}

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
	IsProject        bool
}

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"` //
	Status            *TaskStatus   `json:"ss,omitempty"`
	IsProject         *Boolean      `json:"tp,omitempty"`
	Title             *string       `json:"tt,omitempty"`
	Note              *string       `json:"nt,omitempty"`
	AreaIDs           *[]string     `json:"ar,omitempty"`
	ParentTaskIDs     *[]string     `json:"pr,omitempty"`
	TagIDs            []string      `json:"tg,omitempty"`
	InTrash           *bool         `json:"tr,omitempty"`
	RecurrenceTaskIDs *[]string     `json:"rt,omitempty"`
	Schedule          *TaskSchedule `json:"st,omitempty"`
	ActionGroupIDs    *[]string     `json:"agr,omitempty"`
}

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

type TaskSchedule 

type TaskSchedule int

TaskSchedule describes when a task is scheduled 

const (
	// TaskScheduleToday indicates tasks which should be completed today
	TaskScheduleToday TaskSchedule = 0
	// TaskScheduleAnytime indicates tasks which can be completed anyday
	TaskScheduleAnytime TaskSchedule = 1
	// TaskScheduleSomeday indicates tasks which might never be completed
	TaskScheduleSomeday TaskSchedule = 2
)

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 (TaskStatus) String 

func (i TaskStatus) String() string

type Timestamp 

type Timestamp time.Time

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

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 convers a timestamp into unix nano representation

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

type VerifyResponse 

type VerifyResponse struct {
	SLAVersionAccepted string          `json:"SLA-version-accepted"`
	Issues             json.RawMessage `json:"issues"`
	Status             AccountStatus   `json:"status"`
}

VerifyResponse contains details about your account

Source Files

View all Source files

Directories

Path Synopsis
cmd
thingsweb command
thingsweb/statik
state
memory

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.