Headquarters

Ruby wrapper for the headquarters API

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

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

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

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)

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')

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('miguel@subvisual.co')
client.members.search('Miguel')

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')

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: contact@subvisual.co, app_name: test will become contact+test@subvisual.co. This is useful for filtering and labeling.

client.email.deliver(to: 'miguel@subvisual.co,zamith@subvisual.co', 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: 'example@email.com', subjet: 'Subject', app_name: 'MyApp'
  end
end

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

bundle install
bundle exec rake

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