{"id":17964812,"url":"https://github.com/tgrk/erlpocket","last_synced_at":"2025-03-25T06:31:03.993Z","repository":{"id":7145625,"uuid":"8443335","full_name":"tgrk/erlpocket","owner":"tgrk","description":"An Erlang library for Pocket API","archived":false,"fork":false,"pushed_at":"2019-05-17T18:39:45.000Z","size":1174,"stargazers_count":9,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-19T09:40:43.685Z","etag":null,"topics":["api-client","erlang","erlang-library","getpocket","pocket-api"],"latest_commit_sha":null,"homepage":null,"language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tgrk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-26T22:17:50.000Z","updated_at":"2023-07-24T19:45:52.000Z","dependencies_parsed_at":"2022-09-26T17:11:10.069Z","dependency_job_id":null,"html_url":"https://github.com/tgrk/erlpocket","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrk%2Ferlpocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrk%2Ferlpocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrk%2Ferlpocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgrk%2Ferlpocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tgrk","download_url":"https://codeload.github.com/tgrk/erlpocket/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245413618,"owners_count":20611350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","erlang","erlang-library","getpocket","pocket-api"],"created_at":"2024-10-29T12:08:50.680Z","updated_at":"2025-03-25T06:31:03.763Z","avatar_url":"https://github.com/tgrk.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CircleCI](https://circleci.com/gh/tgrk/erlpocket/tree/master.svg?style=svg)](https://circleci.com/gh/tgrk/erlpocket/tree/master)\n[![Hex pm](http://img.shields.io/hexpm/v/erlpocket.svg?style=flat)](https://hex.pm/packages/erlpocket)\n[![codecov.io](https://codecov.io/github/tgrk/erlpocket/coverage.svg?branch=master)](https://codecov.io/github/tgrk/erlpocket?branch=master)\n\n# erlpocket\n\nAn Erlang library for Pocket API (www.getpocket.com) v3. For more details see [documentation][1].\n\n## Fetch dependencies and compile\n\nProject depends on [jiffy][3] library for JSON parsing and uses default HTTP client (httpc).\n\n    $ rebar3 update compile\n\nor\n\n    $ rebar get-deps compile\n\n## Changes with version 2.x.x\n\nNew version breaks backward compatiblity due to replacing old jiffy style proplists with maps. This should be more convenient to\nuse with latest versions of Erlang. Another big change is that API favors binary input over string input eg. for url when calling add API.\n\n## Quick start\n\nTo run all required dependencies start with:\n\n```erlang\n_ = application:ensure_all_started(erlpocket).\n```\n\nView the [Error and Response Headers Documentation][7] for detailed information about API errors. Also check the [Rate Limits][8] of API.\n\n### Authentication\n\nThe Pocket API uses custom implementation of oAuth 2.0 for authentiaction.\nThis library provide helper functions to authorize your application.\n\n#### Obtain a platform consumer key\n\nFirst you have to [register][3] your application to get consumer key.\n\n#### Obtain a request token\n\n```erlang\nRedirectUri = \u003c\u003c\"http://www.foo.com/\"\u003e\u003e,\nConsumerKey = \u003c\u003c\"app-consumer-key\"\u003e\u003e,\n{ok, #{code := Code}} = erlpocket:request_token(ConsumerKey, RedirectUri).\n```\n\nUse returned security token (code) to get URL that will authorize your\napplication on Pocket website.\n\n```erlang\nUrl = erlpocket:get_authorize_url(Code, RedirectUri).\n```\n\n#### Convert a request code into Pocket access token\n\n```erlang\n{ok, #{access_token := AccessToken, username := Username}} = erlpocket:authorize(ConsumerKey, Code).\n```\n\n### Working with content API\n\nAfter sucessfull authentication you are ready call add/modify and retrieve functions.\n\n#### General\n\nYou can also get content statistics, but it is just call on top of retrieve so it can take quite some time.\n\n```erlang\n{ok, Stats} = erlpocket:stats(ConsumerKey, AccessToken).\n```\n\nValidate API params:\n\n```erlang\ntrue = erlpocket:is_valid_param(add, #{title =\u003e \u003c\u003c\"Foobar\"\u003e\u003e, url =\u003e \u003c\u003c\"http://foobar\"\u003e\u003e}).\ntrue = erlpocket:is_valid_param(retrieve, #{tag =\u003e \u003c\u003c\"Foobar\"\u003e\u003e}).\n```\n\n#### Retrieve API\n\nTo [get][4] content use following call:\n\n```erlang\n{ok, Response} = erlpocket:retrieve(ConsumerKey, AccessToken, #{tag =\u003e \u003c\u003c\"erlang\"\u003e\u003e}).\n```\n\nTo validate retrieve query there is a helper:\n\n```erlang\ntrue = erlpocket:is_valid_query(#{contentType =\u003e video}).\n```\n\n#### Add API\n\n[Add][5] new content simply by calling:\n\n```erlang\n{ok, #{\u003c\u003c\"item\"\u003e := _}} = erlpocket:add(ConsumerKey, AccessToken, \u003c\u003c\"http://foobar/\"\u003e\u003e).\n```\n\nor function with different arrity.\n\n#### Modify API\n\n[Update][6] existing content. There are multiple helpers to ease work with this API call.\n\n##### Helpers on top of Modify API\n\nDelete an existing content:\n\n```erlang\nItemId = \"123\",\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:delete(ConsumerKey, AccessToken, ItemId).\n```\n\nArchive an existing content:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:archive(ConsumerKey, AccessToken, ItemId).\n```\n\nMark an existing content as unread:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:readd(ConsumerKey, AccessToken, ItemId).\n```\n\nMark an existing content as favorite:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:favorite(ConsumerKey, AccessToken, ItemId).\n```\n\nRemove an existing content from favorites:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:unfavorite(ConsumerKey, AccessToken, ItemId).\n```\n\nAdd multiple tags to existing item:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\nTags = [\u003c\u003c\"foo\"\u003e\u003e, \u003c\u003c\"bar\"\u003e\u003e],\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:tags_add(ConsumerKey, AccessToken, ItemId, Tags).\n```\n\nRemove multiple tags from an existing item:\n\n```erlang\nItemId = \"123\",\nTags = [\u003c\u003c\"foo\"\u003e\u003e],\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:tags_remove(ConsumerKey, AccessToken, ItemId, Tags).\n```\n\nReplace multiple tags from an existing item:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\nNewTags = [\u003c\u003c\"foo1\"\u003e\u003e, \u003c\u003c\"bar1\"\u003e\u003e],\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:tags_replace(ConsumerKey, AccessToken, ItemId, NewTags).\n```\n\nRemove multiple tags from an existing item:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:tags_clear(ConsumerKey, AccessToken, ItemId).\n```\n\nRename tag of an existing item:\n\n```erlang\nItemId = \u003c\u003c\"123\"\u003e\u003e,\n{ok, #{\u003c\u003c\"action_results\"\u003e\u003e := [true], \u003c\u003c\"status\"\u003e\u003e := 1}} = erlpocket:tag_rename(ConsumerKey, AccessToken, ItemId, \u003c\u003c\"foo\"\u003e\u003e, \u003c\u003c\"foo1\"\u003e\u003e).\n```\n\n## Example\n\nFor 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).\n\n[1]: http://getpocket.com/developer/docs/overview\n[2]: http://getpocket.com/developer/apps/new\n[3]: https://github.com/davisp/jiffy\n[4]: http://getpocket.com/developer/docs/v3/retrieve\n[5]: http://getpocket.com/developer/docs/v3/add\n[6]: http://getpocket.com/developer/docs/v3/modify\n[7]: http://getpocket.com/developer/docs/errors\n[8]: http://getpocket.com/developer/docs/rate-limits\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgrk%2Ferlpocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftgrk%2Ferlpocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgrk%2Ferlpocket/lists"}