Tarpon

A Ruby interface to RevenueCat's REST API.

Installation | Usage | API Reference

Installation

Add this line to your application's Gemfile:

gem 'tarpon'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tarpon

Usage

Configuration

Tarpon::Client.configure do |c|
  c.public_api_key = 'your-public-key'
  c.secret_api_key = 'your-secret-key'
  c.timeout        = 5 # a global timeout in seconds for http requests to RevenueCat server, default is 5 seconds
end

Get your credentials from the RevenueCat dashboard. Read more about authentication on the RevenueCat docs.

Performing requests

Get or create a subscriber

Tarpon::Client
  .subscriber('app_user_id')
  .get_or_create

Delete a subscriber

Tarpon::Client
  .subscriber('app_user_id')
  .delete

Grant a promotional entitlement

Tarpon::Client
  .subscriber('app_user_id')
  .entitlements('entitlement_id')
  .grant_promotional(duration: 'daily', start_time_ms: 1582023714931)

Be aware that RevenueCat doesn't create the subscriber automatically. If the app_user_id doesn't exist, the request will fail with a 404 Not Found. Perform a Tarpon::Client.subscriber('app_user_id').get_or_create beforehand to make sure the subscriber exists when granting promotional entitlements:

Tarpon::Client.subscriber('app_user_id').get_or_create # subscriber is created

Tarpon::Client
  .subscriber('app_user_id')
  .entitlements('entitlement_id')
  .grant_promotional(duration: 'daily', start_time_ms: 1582023714931)

Check the endpoint reference for valid duration values, Tarpon does not perform any input validation.

List offerings available to subscriber

Tarpon::Client
  .subscriber('app_user_id')
  .offerings
  .list(platform)

Where platform is one either ios, android, macos, uikitformac or stripe.

Read more about offerings here

Revoke a promotional entitlement

Tarpon::Client
  .subscriber('app_user_id')
  .entitlements('entitlement_id')
  .revoke_promotional

Create a purchase

platform = 'ios' # possible values: android|ios|stripe
payload = {
  app_user_id: 'app_user_id',
  fetch_token: 'fetch_token',
}
Tarpon::Client
  .receipt
  .create(platform: platform, payload)

Check the endpoint reference for a valid purchase payload.

Defer billing (android)

Tarpon::Client
  .subscriber('app_user_id')
  .subscriptions('product_id')
  .defer(expiry_time_ms: 1582023715118)

Handling responses

By default, Tarpon will raise custom errors in the following occasions:

• Tarpon::NotFoundError will be raised when RevenueCat server responds with a not found status code.

• Tarpon::InvalidCredentialsError will be raised when RevenueCat server responds with unauthorized status code, e.g. invalid API key.

• Tarpon::ServerError will be raised when RevenueCat server responds with internal error status code (5xx).

• Tarpon::TimeoutError will be raised when RevenueCat server takes too long to respond, based on Tarpon::Client.timeout.

For success and client error status codes, Tarpon will parse it to the response object.

The Response object

response = Tarpon::Client
             .subscriber('app_user_id')
             .get_or_create

The plain response body from RevenueCat is stored in the raw attribute:

response.raw
# {
#   request_date_ms: 1582029851163,
#   subscriber: {
#     original_app_user_id: 'app_user_id',
#     ...
#   }
# }

Use the success? method to know whether the request was successful:

response.success? # boolean

The subscriber entity is stored in the subscriber attribute when the subscriber object is returned by RevenueCat:

response.subscriber # <Tarpon::Entity::Subscriber>

The subscriber entity

The subscriber entity comes with a few goodies that might save you some time.

Get the user entitlements:

response.subscriber.entitlements

Get only active user entitlements:

response.subscriber.entitlements.active

The entitlement entity

response.subscriber.entitlements.each do |entitlement|
  entitlement.expires_date # Ruby time parsed from iso8601
  entitlement.active? # true if expires_date > Time.now.utc
end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fishbrain/tarpon.

Clone the repository using

$ git clone https://github.com/fishbrain/tarpon.git && cd tarpon

Install development dependencies through Bundler

$ bundle install

Run tests and linter using

$ bundle exec rspec && bundle exec rubocop

License

The gem is available as open source under the terms of the MIT License.