robinjmurphy/node-readability-api

## node-readability-api

[![Build Status](https://travis-ci.org/robinjmurphy/node-readability-api.svg?branch=master)](https://travis-ci.org/robinjmurphy/node-readability-api) [![Code Climate](https://codeclimate.com/github/robinjmurphy/node-readability-api/badges/gpa.svg)](https://codeclimate.com/github/robinjmurphy/node-readability-api)

This is a Node client for the [Readability](http://www.readability.com/) API. It supports the [Reader API](http://www.readability.com/developers/api/reader), [Parser API](http://www.readability.com/developers/api/parser) and [Shortener API](http://www.readability.com/developers/api/shortener).

### Installation

```bash
npm install --save readability-api
```

### Usage

Initialize the client

```javascript
var readability = require('readability-api');

readability.configure({
    consumer_key: 'some_consumer_key',
    consumer_secret: 'some_consumer_secret',
    parser_token: 'some_parser_token'
});
```

### Authentication

Retrieve an OAuth access token and access token secret for a user

```javascript
readability.xauth('some_username', 'some_password', function (err, tokens) {
  // Use tokens.oauth_token and tokens.oauth_token_secret when creating a Reader API client
})
```

#### Reader API

To use the Reader API, create a Reader object using an OAuth token and token secret

```javascript
var reader = new readability.reader({
  access_token: 'some_access_token',
  access_token_secret: 'some_access_token_secret'
});
```

##### User information

```javascript
// Get information about the current user
reader.user(function (err, user) {
  //...
});
```

##### Bookmarks

```javascript
// Get all bookmarks - response contains both metadata (pagination etc.) and an array of bookmarks
reader.bookmarks(options, function (err, bookmarks) {
   //...
});

// Get a bookmark by its id
reader.bookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Add a bookmark - returns the created bookmark
reader.addBookmark('http://some.bookmark.url.com/article.html', function (err, bookmark) {
   //...
});

// Remove a bookmark - success is a boolean
reader.removeBookmark('some_bookmark_id', function (err, success) {
   //...
});

// Archive a bookmark - returns the archived bookmark
reader.archiveBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Unarchive a bookmark - returns the bookmark
reader.unarchiveBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Favourite a bookmark - returns the favourited bookmark
reader.favouriteBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

// Unavourite a bookmark - returns the bookmark
reader.unfavouriteBookmark('some_bookmark_id', function (err, bookmark) {
   //...
});

```

##### Tags

```javascript
// Get all of the current user's tags - returns an array of tags
reader.userTags(function (err, tags) {
   //...
});

// Get all of the tags for a bookmark - returns an array of tags
reader.tags('some_bookmark_id', function (err, tags) {
   //...
});

// Add tags to a bookmark - returns an array of tags
reader.addTags('some_bookmark_id', ['tag1', 'tag2', 'tag3'], function (err, bookmark) {
    //...
});

// Remove a tag from a bookmark - returns the bookmark
reader.removeTag('some_bookmark_id', 'some_tag_id', function (err, bookmark) {
   //...
});
```

##### Articles

```javascript
// Get a single article
reader.article('some_article_id', function (err, article) {
   //...
});
```

#### Parser API

```javascript
// Create a parser object
var parser = new readability.parser();

// Parse an article
parser.parse('http://some.bookmark.url.com/article.html', function (err, parsed) {
  //...
});

// Get the Parser confidence level - returns a number between 0 and 1
parser.confidence('http://some.bookmark.url.com/article.html', function (err, confidence) {
  //...
});
```

#### Shortener API

```javascript
// Create a shortener object
var shortener = new readability.shortener()

// Create a short URL - returns the short URL as a string and additional URL data
shortener.shorten('http://www.example.com/article.html', function(err, shortUrl, data) {
  //...
});

// Get information about a short URL
shortener.url('some_url_id', function(err, url) {
  //...
});
```