pocket-lib.el

pocket-lib.el copied to clipboard

• pocket-lib.el

This is a simple library for accessing the [[https://getpocket.com/developer/docs/v3/][getpocket.com API]]. It should be considered in late alpha/early beta status at the moment: there are no known bugs, and some features may still be added. The API is not expected to change significantly, but backward-incompatible changes might still be made (although this is unlikely).

• Installation

** MELPA

Just install the =pocket-lib= package. :)

** Manual

Put =pocket-lib.el= in your =load-path=.

• Usage

** Authorize

First you must authorize this library to access your Pocket account.

1. Open your web browser to the Pocket web site, and log out of Pocket. (It seems to only work if you are logged out.)
2. Run =pocket-lib-get= (this is not an interactive command, so you should call it in the minibuffer like ~(pocket-lib-get)~; typically this will be handled for you by packages that use this library). A URL will be copied to the clipboard and kill-ring.
3. Visit that URL in your browser, and authorize it.
4. Run =pocket-lib-get= again. If it worked, you should see an ugly list of data containing the first 10 items on your list.

Now you can use the library.

Note: Please /ignore/ any =Page Not Found= error you might see on the Pocket Web site after authorizing. Just run the ~pocket-reader~ command after authorizing, and it should work. You can verify that authorization completed by checking the file =~/.cache/emacs-pocket-lib-token.json=.

** Functions

For more detailed information on each function, use =describe-function=.

• =pocket-lib-get= Get items on the reading list. Call with keyword arguments, as listed in the API docs, to get different kinds of items (e.g. archived, favorited, tagged, etc).
• =pocket-lib-add-urls= Add one or more URLs to reading list.

These functions operate on one or more items, which should be alists, structured like items retrieved with =pocket-lib-get=, having at least the =item_id= property.

• =pocket-lib-archive= Archive items.

• =pocket-lib-readd= Re-add items to reading list (not a new URL).

• =pocket-lib-delete= Delete items from reading list.

• =pocket-lib-favorite= Mark items as a favorite.

• =pocket-lib-unfavorite= Unmark items as a favorite.

• =pocket-lib--tags-action= Execute /ACTION/ with /TAGS/ on /ITEMS/. /ACTION/ should be a tags action from the API. (Specific tags actions may be added separately in the future, in which case this function would be considered private, so it will remain named with a double-hyphen.)

• =pocket-lib--process-tags= Return simple list of strings for /TAGS/ structure as returned by Pocket API. The Pocket API returns items' tags in a peculiar structure. This function turns that structure into a simple list of tags. This is probably useful for users of this library, but the double-hyphen name will remain for now.

• Changelog

** v0.3-pre

Changes

• Use [[https://github.com/alphapapa/plz.el][plz]] HTTP library.

Fixes

• Ensure token file is writable. ([[https://github.com/alphapapa/pocket-lib.el/pull/1][#1]]. Thanks to [[https://github.com/alphapapa/pocket-lib.el/issues?q=is%3Apr+is%3Aopen+author%3Akevinjfoley][Kevin Foley]].)

Acknowledgments

• Thanks to [[https://github.com/joshbax189][Josh B]] for reporting and helping to fix a bug with initial authentication ([[https://github.com/alphapapa/pocket-lib.el/pull/7][#7]]).

** v0.2

Changes

• Use =request='s =url-retrieve= backend to workaround [[https://github.com/tkf/emacs-request/issues/92][bug]].

** v0.1

Initial release.

• Credits

This package is based on [[https://github.com/lujun9972/pocket-api.el][pocket-api.el]] by [[https://github.com/lujun9972/pocket-api.el][DarkSun/lujun9972]], which is based on [[https://github.com/pterygota/el-pocket][el-pocket]] by [[https://github.com/pterygota/el-pocket][Tod Davies]]. It has essentially been completely written; no code remains except =pocket-lib-default-extra-headers=, a few lines in the call to =request=, and the consumer key is currently the same.

• License

GPLv3