Hull Ruby client

Installation

Add this line to your application's Gemfile:

gem 'hullio'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hullio

Usage

Configuration

Hull.configure do |c|
  c.app_id = "your-app-id"
  c.app_secret = "your-app-secret"
  c.org_url = "http://ORG-NAMESPACE.hullapp.io"
end

In Rails, you can include this in an initializer.

Making API Calls

get, put, post and delete methods are directly available on Hull.

examples:

# Get the current app
Hull.get('app')

# Get the a list of comments on the current app (with pagination)
Hull.get('app/comments', limit: 10, page: 2)

# Update an existing object
Hull.put('app', { name: 'My Super App' })

with Hull entities :

entityId = Hull::Entity.encode('http://example.com')
#=>"~aHR0cDovL2V4YW1wbGUuY29t"

Hull.get(entityId)
Hull.put(entityId)
Hull.delete(entityId)

# Get comments on the Entity identified by 'http://example.com' 
Hull.get(entityId+'/comments')

# Decoding an encoded entity:
Hull::Entity.decode(entityId)
#=>'http://example.com'

Making API calls as as a User

# From its user ID
Hull.as('51fa7afd09e50d11f1000002').get('me')

# Find a User based on his identity from an external service:

# Find user from his Twitter handle:
Hull.as('twitter:hull').get('me')

# Find user from his Faceboo ID
Hull.as('facebook:fb_uid').get('me')

# Find user from his ID in your app (BYOU)
Hull.as('external:3637').get('me')

# From a User in your database, with lazy creation (Checkout [Bring your own Users Documentation](http://hull.io/docs/users/byou))
userHash = {external_id:'1234', name:'Romain', email:'[email protected]'}
Hull.as(userHash).get('me')

Getting the current User

Hull.authenticate_user allows you to retrieve the current User's ID.

Rails

class MyController < ApplicationController
  def current_hull_user_id
    @current_hull_user_id ||= Hull.authenticate_user(request.env)
  end

  def current_hull_user
    # You probably should cache this or record this information in a session
    # to avoid making calls to Hull's API on each request
    @current_hull_user ||= Hull.get(current_hull_user_id)
  end

end

Bring your own users

Using JWT, you can use Hull with Users from your system. To use this feature, you just have to add a accessToken key at the initialization of hull.js. Read more at http://hull.io/docs/users/byou

In your view :

<script>
  Hull.init({
    appId:  "<%= Hull.app_id %>",
    orgUrl: "<%= Hull.org_url %>",
    accessToken: "<%= Hull.user_token({external_id: "123", email: "[email protected]", name: "Bill Evans" })  %>"
  });
</script>

Hooks

Hooks allow you to be notified every time an object in your app is created, updated or deleted.

require 'hull/middlewares/hook'

# path option default is '/__hull-hook__'
use Hull::Middlewares::Hook, path: '/hullook', secret: ENV['HULL_APP_SECRET'] do |event, request|
  # Do something with event
end

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request