subvisual/headquarters-ruby

Ruby wrapper for the headquarters API used at Group Buddies

Headquarters

Ruby wrapper for the headquarters API

Installation

Add this line to your application's Gemfile:

gem 'headquarters'

Or if you want the edge version:

gem 'headquarters', github: 'subvisual/headquarters-ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install headquarters

Configuration

You can set the API's base endpoint and port:

Headquarters.api_base = "0.0.0.0"
Headquarters.api_port = 3000

Logging

Out of the box headquarters-ruby will log all requests and responses to STDOUT, you can use any logger you want, though:

Headquarters.logger = Logger.new(STDERR)

Usage

You must first instantiate a client:

client = Headquarters.new

You most likely want to authenticate to use protected endpoints (such as sending emails). You can do so by passing the credentials to the constructor:

client = Headquarters.new(client_id: 'your_client_id', client_secret: 'your_client_secret')

The main client contains namespaces that give you access to different features of Headquarters. For example, the email API can be accessed via client.email. If your applications needs only to send emails, and doesn't use any other features, you can instantiate an email client directly instead:

email_client = Headquarters::Client::Email.new(client_id: 'your_client_id', client_secret: 'your_client_secret')

Members

To retrieve a collection of all members of the team you might use the all operation:

client.members.all

Or you can search for a specific query

client.members.search('[email protected]')
client.members.search('Miguel')

Github

Within the github namespace, you can use the pull_requests method to get a list of all open Pull Requests in the Group Buddies organization:

client.github.pull_requests

You can filter these results using anything that github takes in the q parameters of its search API. For instance, if you want to get only the open pull requests, you might do:

client.github.pull_requests(query: 'is:open')

Emails

You can send emails for Group Buddies addresses (Any non-GB addresses will be filtered out).

app_name can be set to be appended to the sender. i.e. from: [email protected], app_name: test will become [email protected]. This is useful for filtering and labeling.

client.email.deliver(to: '[email protected],[email protected]', subject: 'custom subject', body: '<b>HTML body</b>', app_name: 'hq')

When using rails you can use headquarters as the delivery method, and transparently send emails using ActiveMailer as usual:

# config/initializers/mailer.rb
ActionMailer::Base.delivery_method = :headquarters

Headquarters::RailsDeliveryMethod.credentials = {
  client_id: 'your_client_id',
  client_secret: 'your_client_secret'
}

Using this method, app_name is also available as a header or parameter to the mail function

class CustomMailer < ActionMailer::Base
  # option 1, default header
  default 'app_name' => 'MyApp'

  def email
    # option 2, as an argument
    mail to: '[email protected]', subjet: 'Subject', app_name: 'MyApp'
  end
end

Testing

To run the tests (including style tests with Rubucop) install all the dependencies and run the default rake task:

bundle install
bundle exec rake

Contributing

1. Fork it ( https://github.com/[my-github-username]/headquarters/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

headquarters-ruby's Issues

require placed on the wrong place

Like we found out yesterday, the require for the endpoints module is done on the wrong place. Right now it's on the members.rb but it's used in other places, not only on this file.

Update README with OAuth support

OAuth support has been added to the gem, but the README does not yet reflect this.

Migrate docs to the Wiki

@zamith just letting you know I'm doing this now, the README is getting out of hand