cloud

Documentation

Overview

Package cloud is the second version of the client implemented for interacting with the Remarkable Cloud API. It has been initiated because the first version was not decoupled enough and could not be easily used by external packages. The first version of the package is still available for backward compatility purposes.

The aim of this package is to provide simple bindings to the Remarkable Cloud API. The design has been mostly discussed here: https://github.com/juruen/rmapi/issues/54. It has to be high level in order to let a user easily upload, download or interact with the storage of a Remarkable device.

The SplitBrain reference has helped a lot to explore the Cloud API has there is no official API from Remarkable. See: https://github.com/splitbrain/ReMarkableAPI/wiki.

For interacting with the API, we decoupled the process of authentication from the actual storage operations. The authentication is not handled in this package. See the auth package from this project.

We tend to follow the good practices from this article to write a modular http client: https://medium.com/@marcus.olsson/writing-a-go-client-for-your-restful-api-c193a2f4998c.

Index

• Constants
• type Client
  • func NewClient(httpClient *http.Client) *Client
  • func (c *Client) CreateFolder(name string, parent string) (string, error)
  • func (c *Client) Delete(uuid string) error
  • func (c *Client) Download(uuid string, w io.Writer) error
  • func (c *Client) Get(uuid string) (Document, error)
  • func (c *Client) List() ([]Document, error)
  • func (c *Client) Metadata(doc Document) error
  • func (c *Client) Upload(uuid string, name string, r io.Reader) error
  • func (c *Client) UploadDocument(doc Document, r io.Reader) error
• type Document
  • func (d Document) String() string

Constants

const (
	// DirectoryType is used as directory type.
	DirectoryType = "CollectionType"
	// DocumentType is used a regular document type.
	DocumentType = "DocumentType"
)

Types

type Client

type Client struct {
	// By making the base URL configurable we can make it
	// testable by passing the URL of a httptest.Server.
	// That also means that the Client is acting upon a same base URL for all requests.
	BaseURL *url.URL

	UserAgent string
	// contains filtered or unexported fields
}

A Client manages communication with the Remarkable Cloud API.

func NewClient

func NewClient(httpClient *http.Client) *Client

NewClient instanciates and configures the default URL and user agent for the http client.

func (*Client) CreateFolder

func (c *Client) CreateFolder(name string, parent string) (string, error)

CreateFolder is a first class method used to create a new folder.

It takes a folder name as parameter and an optional parent UUID to create the folder in a subdirectory. If an empty string is provided, the folder will be created at the root.

The UUID of the created folder is returned.

func (*Client) Delete

func (c *Client) Delete(uuid string) error

Delete is a first class method used to delete a document or folder.

func (*Client) Download

func (c *Client) Download(uuid string, w io.Writer) error

Download is a first class method used to download the actual content of a document.

It takes a uuid as parameter and an io.Writer that will be used to write the content. By using an io.Writer, the content can be committed to a file but also in response to an http call for example.

The content received will be a zip file containing all the document files. To make use of it, you can have a look to the archive package.

func (*Client) Get

func (c *Client) Get(uuid string) (Document, error)

Get is a first class method used to fetch information of a document.

It takes a uuid as parameter and a Document is returned to the end user.

func (*Client) List

func (c *Client) List() ([]Document, error)

List is a first class method used to fetch the list of all documents on a device.

It returns a list of Documents.

func (*Client) Metadata

func (c *Client) Metadata(doc Document) error

Metadata is a first class method used to update metadata of an existing document.

It takes a Document as input containing the metadata changes that will be sent to the API.

This method can be used to make a document visible, to move, rename, bookmark a document.

Calling this method will reset the ModifiedClient time to now. If the document Version is not explicitly defined, it will be defined by fetching the current document version and adding one.

func (*Client) Upload

func (c *Client) Upload(uuid string, name string, r io.Reader) error

Upload is a first class method used to upload a new document.

A newly generated uuid should be provided and a name should be given.

An io.Reader is expected as parameter to provide the content of the document. This way, we can upload a content not only from a file but as well from other sources.

The content should be shaped as a zip file as expected by the Remarkable. You can have a look to the archive package to help easily creating a correctly formatted file.

func (*Client) UploadDocument

func (c *Client) UploadDocument(doc Document, r io.Reader) error

Upload is a first class method used to upload content to a document.

The Document given as parameter will identify which real document to target. If the Document uuid already exists, the content will be updated. If not, a new document will be created. For creating a new document however, you may want to use the Upload method instead.

An io.Reader is expected as parameter to provide the content of the document. This way, we can upload a content not only from a file but as well from other sources.

The content should be shaped as a zip file as expected by the Remarkable. You can have a look to the archive package to help easily creating a correctly formatted file.

type Document

type Document struct {
	ID          string
	Version     int
	Type        string
	Name        string
	CurrentPage int
	Bookmarked  bool
	Parent      string
}

Document represents a human readable format of a Remarkable document. It is transformed into a more technical object and used as a payload or response during http calls with the Remarkable API.

func (Document) String

func (d Document) String() string

String dictates how to print a Document object.