erlpocket

An Erlang library for Pocket API (www.getpocket.com) v3. For more details see documentation.

Fetch dependencies and compile

Project depends on jiffy library for JSON parsing and uses default HTTP client (httpc).

$ rebar3 update compile

or

$ rebar get-deps compile

Changes with version 2.x.x

New version breaks backward compatiblity due to replacing old jiffy style proplists with maps. This should be more convenient to use with latest versions of Erlang. Another big change is that API favors binary input over string input eg. for url when calling add API.

Quick start

To run all required dependencies start with:

_ = application:ensure_all_started(erlpocket).

View the Error and Response Headers Documentation for detailed information about API errors. Also check the Rate Limits of API.

Authentication

The Pocket API uses custom implementation of oAuth 2.0 for authentiaction. This library provide helper functions to authorize your application.

Obtain a platform consumer key

First you have to register your application to get consumer key.

Obtain a request token

RedirectUri = <<"http://www.foo.com/">>,
ConsumerKey = <<"app-consumer-key">>,
{ok, #{code := Code}} = erlpocket:request_token(ConsumerKey, RedirectUri).

Use returned security token (code) to get URL that will authorize your application on Pocket website.

Url = erlpocket:get_authorize_url(Code, RedirectUri).

Convert a request code into Pocket access token

{ok, #{access_token := AccessToken, username := Username}} = erlpocket:authorize(ConsumerKey, Code).

Working with content API

After sucessfull authentication you are ready call add/modify and retrieve functions.

General

You can also get content statistics, but it is just call on top of retrieve so it can take quite some time.

{ok, Stats} = erlpocket:stats(ConsumerKey, AccessToken).

Validate API params:

true = erlpocket:is_valid_param(add, #{title => <<"Foobar">>, url => <<"http://foobar">>}).
true = erlpocket:is_valid_param(retrieve, #{tag => <<"Foobar">>}).

Retrieve API

To get content use following call:

{ok, Response} = erlpocket:retrieve(ConsumerKey, AccessToken, #{tag => <<"erlang">>}).

To validate retrieve query there is a helper:

true = erlpocket:is_valid_query(#{contentType => video}).

Add API

Add new content simply by calling:

{ok, #{<<"item"> := _}} = erlpocket:add(ConsumerKey, AccessToken, <<"http://foobar/">>).

or function with different arrity.

Modify API

Update existing content. There are multiple helpers to ease work with this API call.

Helpers on top of Modify API

Delete an existing content:

ItemId = "123",
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:delete(ConsumerKey, AccessToken, ItemId).

Archive an existing content:

ItemId = <<"123">>,
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:archive(ConsumerKey, AccessToken, ItemId).

Mark an existing content as unread:

ItemId = <<"123">>,
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:readd(ConsumerKey, AccessToken, ItemId).

Mark an existing content as favorite:

ItemId = <<"123">>,
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:favorite(ConsumerKey, AccessToken, ItemId).

Remove an existing content from favorites:

ItemId = <<"123">>,
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:unfavorite(ConsumerKey, AccessToken, ItemId).

Add multiple tags to existing item:

ItemId = <<"123">>,
Tags = [<<"foo">>, <<"bar">>],
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:tags_add(ConsumerKey, AccessToken, ItemId, Tags).

Remove multiple tags from an existing item:

ItemId = "123",
Tags = [<<"foo">>],
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:tags_remove(ConsumerKey, AccessToken, ItemId, Tags).

Replace multiple tags from an existing item:

ItemId = <<"123">>,
NewTags = [<<"foo1">>, <<"bar1">>],
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:tags_replace(ConsumerKey, AccessToken, ItemId, NewTags).

Remove multiple tags from an existing item:

ItemId = <<"123">>,
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:tags_clear(ConsumerKey, AccessToken, ItemId).

Rename tag of an existing item:

ItemId = <<"123">>,
{ok, #{<<"action_results">> := [true], <<"status">> := 1}} = erlpocket:tag_rename(ConsumerKey, AccessToken, ItemId, <<"foo">>, <<"foo1">>).

Example

For example usage of this library please refer to tests. Note that tests are are using real API endpoints (copy template api.sample.txt as api.txt and fill your Pocket Appplication creadentials there).