epistrephein / rarbg

Ruby client for the RARBG Torrent API.

RARBG

Ruby client for the RARBG Torrent API

RubyGems — Documentation

Installation

Install as a gem

$ gem install rarbg

Or add it to your Gemfile and execute bundle install

gem 'rarbg', '~> 2.0'

Usage

This gem wraps all API methods available from RARBG TorrentAPI.

An authentication token is automatically generated on the first request, stored with a timestamp and renewed every 800 seconds.

Rate limit (1req/2s) is automatically enforced.

Check out the full documentation for details on all methods and parameters.

Getting started

Require the gem and initialize a new RARBG::API object.

require 'rarbg'

rarbg = RARBG::API.new

Methods

Use list to list torrents. Additional parameters are passed as keyword arguments and can be mixed together.

All successful method calls return an array of hashes (or an empty array for no results).

# List last 100 torrents.
rarbg.list(limit: 100)

# List torrents with at least 20 seeders, sorted by seeders.
rarbg.list(min_seeders: 20, sort: :seeders)

# List torrents with extended json infos.
rarbg.list(format: :json_extended)

Use search to search torrents. One search type parameter among string, imdb, themoviedb and tvdb is required.

# Search torrents using literal string query.
rarbg.search(string: 'Force Awakens')

# Search by IMDB id, in `Movies/x264/1080` and `Movies/x264/720`.
rarbg.search(imdb: 'tt2488496', category: [44, 45])

# Search unranked torrents by TheMovieDB id, sorted by last.
rarbg.search(themoviedb: 140607, ranked: false, sort: :last)

These methods are also available from the top module namespace for convenience.

RARBG.list(sort: :leechers, min_leechers: 10)

RARBG.search(string: 'Star Wars', category: [48])

A list of name/id pairs for each category is available for quick lookup.

RARBG::CATEGORIES
# => { "Movies/XVID"     => 14,
#      "Movies/XVID/720" => 48,
#      "Movies/x264"     => 17,
#      ...

Errors

API endpoint errors will raise a RARBG::APIError exception with the API error message.

rarbg.list(sort: :name)
# => RARBG::APIError: Invalid sort

rarbg.search(string: 'Star Wars', min_seeders: 'notanumber')
# => RARBG::APIError: Invalid value for min_seeders

rarbg.search(imdb: 'tt0121765')
# => RARBG::APIError: Service unavailable (503)

Parameter validation errors on client side will raise an ArgumentError.

rarbg.list('a string instead of an hash')
# => ArgumentError: Expected params hash

rarbg.search(limit: 50)
# => ArgumentError: One search parameter required among: string, imdb, tvdb, themoviedb

Lower level connection errors will raise Faraday::Error subclasses exceptions.

rarbg.search(string: 'a timeout error')
# => Faraday::ConnectionFailed: execution expired

Contributing

Bug reports and pull requests are welcome on GitHub.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Code of Conduct.

You can contribute changes by forking the project and submitting a pull request. To get started:

1. Fork the repo
2. Install the dependencies (bin/setup)
3. Create your feature branch (git checkout -b my-new-feature)
4. Commit your changes (git commit -am 'Add some feature')
5. Pass the test suite (rake spec)
6. Push to the branch (git push origin my-new-feature)
7. Create a new pull request

For more information about contributing to this project, check out CONTRIBUTING.

License

This gem is released as open source under the terms of the MIT License.

rarbg's Issues

How do you do pagination?

My apologies if this I've missed something - but it's not clear from the docs (https://epistrephein.github.io/rarbg/) how you pagination through results?

For example, if search() return 25 results, how do you get to page 2, page 3 etc?