# kat-cr
![build status](https://ci.appveyor.com/api/projects/status/github/raypulver/kat-cr)

kat-cr is a simple, flexible CLI application and node module which searches kat.cr for torrents. The JSON API is no longer fully supported by Kickass Torrents and the RSS feed is also lacking. The primary browser-based search engine provided by Kickass Torrents offers the most features, so that is what this application uses to search for torrents.


## Installation
To use the CLI application, use

```
npm install -g kat-cr
```

This will install an executable `kickass` to your `PATH`.

To use as a module, install to your project with

```
npm install --save kat-cr
```


## CLI Application Usage

A basic torrent search would look something like

```
kickass -c tv south park
```

In this example, the optional -c flag was passed to specify the search category. kat.cr returns search results in sets of 25, and caps results at 10000. You can specify the page # you want returned by passing the -p flag. So if you wanted to go to the second page of South Park TV torrents, you would run

```
kickass south park -c tv -p 2
```

By default, `kickass` will display direct torrent links but if you provide the `-m` or `--magnet` option, the links returned will be the magnet links. As an example:

```
kickass south park -c tv -p 2 -m
```

The torrent titles will be displayed in bold yellow if they are torrents posted by a Kickass Torrents verified member, and there will be a purple `ELITE` qualifier before any torrents posted by a Kickass Torrents elite member.

And that's all there is to it. The application and module orders torrents by seeders in descending order by default. To change this behavior, pass the -f/--field flag or -s/--sorder flag (details on the possible values for these options below). Note that you do not have to surround a multi-word search query in quotes.

## Module usage
To use this module in your application, install it to your project and use

```
var kickass = require('kat-cr');
```

`kat-cr` uses a Promise API; you can perform a basic search with

```
kickass('search query').then(function (results) {
  // do something with results
}, function (err) {
 // handle error
});
```


You can perform an advanced search by passing an object to the function instead of a string. The object can contain the following keys
* `search` {string}: The search query
* `category` {string}: The search category
* `page` {number}: The page # of the returned results
* `field` {string}: The field by which the results are sorted, default is 'seeders'. Other possibilities include 'time\_add', 'files\_count', 'size', and 'leechers'
* `sorder` {string}: The order the results are displayed in, default is 'desc'. Alternatively you can use 'asc'

The object resolved by this promise is designed to mimic the JSON response returned by the currently feature-deficient Kickass Torrent JSON API, but the actual object is a custom `KickassResultGroup` object, which at this stage does not have any methods on its prototype, but contains some properties relevant to the entire search result:
* `results.total_results` {number}: The total amount of torrent results
* `results.link` {string}: Always 'http://kat.cr'
* `results.language` {string}: Using this module you will always get 'en-us'
* `results.list` {Array}: An array containing the torrents and their info

The bulk of the information will be in `results.list`. The properties of a torrent object are:
* `title` {string}: The title of the torrent
* `category` {string}: The category of torrent
* `link` {string}: The link to the torrent page on kat.cr
* `pubDate` {Date}: a Date instance representing the date the torrent was published
* `torrentLink` {string}: The direct http link to the torrent file
* `magnetLink` {string}: The magnet link associated with the torrent
* `files` {number}: The amount of files associated with the torrent
* `comments` {number}: The amount of comments the torrent received on kat.cr
* `hash` {number}: A hash digest of the torrent
* `peers` {number}: The amount of peers associated with the torrent
* `seeds` {number}: The amount of seeders associated the torrent
* `leechs` {number}: The amount of leeches downloading the torrent
* `size` {number}: The size of the files provided by the torrent, in bytes
* `verified` {boolean}: Whether or not the torrent was posted by a Kickass Torrents verified user
* `elite` {boolean}: Whether or not the torrent was posted by a Kickass Torrents elite user
* `id` {string}: The torrent ID on kat.cr that can be used to call API functions

Each item in `results.list` is actually a `KickassResult` object, which currently has the following methods on its prototype:

* `KickassResult#getComments()`: Return a promise that resolves with an array of comment objects, which have an `owner` and a `comment` property representing the screen name of the comment poster and the content of the comment, respectively
* `KickassResult#getDetails()`: Make an HTTP request to the dedicated webpage associated with the torrent result and return a promise which resolves with an object containing additional details about the torrent. At this stage the only additional detail provided by the resolved object is stored in the `description` property, which contains the text-only version of the torrent description


## Example

Log the magnet link and get the comments for the most seeded South Park torrent:

```
kickass({
  search: 'south park',
  field: 'seeders',
  sorder: 'desc',
  category: 'tv'
}).then(function (results) {
  console.log(results.list[0].magnetLink);
  results.list[0].getComments().then(function (comments) {
    // do something with comments
  });
});
```


## Note

The URL to Kickass Torrents is expected to change. In case it has not yet been updated, put the new URL into `config/kickass-url.json`

Always keep your global `kat-cr` package updated.


## Testing

kat-cr is a web scraping module and thus it depends on the structure of the Kickass Torrents search response, as well as the current domain name of the Kickass torrents server. In case of updates to Kickass Torrents, running

```
npm test
```

in the project directory will indicate what exactly went wrong with the attempt to convert a Kickass Torrents search response into a `KickassResultGroup` object, and contributors are invited to submit pull requests correcting the API endpoints, domain name, or CSS selectors.

Make sure `mocha` is installed globally, and that you run `npm install` in the project directory before attempting to run the tests.

## Documentation

The source code is fully documented. To build the documentation, make sure the `grunt-cli` package is installed globally and that you have run `npm install` in the project directory, then run

```
grunt
```

in the project directory. To view the source code documentation, open up doc/index.html in your favorite web browser.


## License

MIT. Feel free to modify and distribute.


## Author

Raymond Pulver IV