# Yammer OAuth2 Client

[![Gem Version](https://badge.fury.io/rb/yammer-oauth2.png)][gem]
[![Build Status](https://api.travis-ci.org/tiabas/yammer-oauth2.png)][travis]
[![Dependency Status](https://gemnasium.com/tiabas/yammer-oauth2.png)][gemnasium]
[![Coverage Status](https://coveralls.io/repos/tiabas/yammer-oauth2/badge.png?branch=master)][coveralls]

[gem]: https://rubygems.org/gems/yammer-oauth2
[travis]: http://travis-ci.org/tiabas/yammer-oauth2
[gemnasium]: https://gemnasium.com/tiabas/yammer-oauth2
[coveralls]: https://coveralls.io/r/tiabas/yammer-oauth2

An Ruby wrapper for Yammer's OAuth2 implementation

For more about the OAuth2 standard checkout: http://tools.ietf.org/html/rfc6749 

## Installation
```sh
gem install yammer-oauth2
```

## Resources
* [Yammer developer Website][yammer]
* [View Source on GitHub][code]
* [Report Issues on GitHub][issues]
* [Website][website]

[website]: http://tiabas.github.com/yammer-oauth2
[code]: https://github.com/tiabas/yammer-oauth2
[issues]: https://github.com/tiabas/yammer-oauth2/issues
[yammer]: https://developer.yammer.com/authentication/

## Usage Examples

```ruby

require 'yammer-oauth2/client'

yammer_client = YammmerOAuth2::Client.new('PRbTcg9qjgKsp4jjpm1pw', 'Xn7kp7Ly0TCY4GtZWkmSsqGEPg10DmMADyjWkf2U')

```

## Authorization Grants
The client wraps around the creation of any given grant and passing in the parameters defined in the configuration
file. The supported grants include Authorization Code and Implicit. They are available via the `authorization_code` and `implicit` methods on a client object.

### Authorization Code

```ruby

# generate authorization url
auth_url = yammer_client.webserver_authorization_url
# => https://www.yammer.com/dialog/oauth/authorize?client_id=PRbTcg9qjgKsp4jjpm1pw&response_type=code

# exchange authorization code for access token. we will get back a Net::HTTPResponse
response = yammer_client.exchange_auth_code_for_token({
    :code => '11a0b0b64db56c30e2ef',
    :redirect_uri => 'https://localhost/callback',
  })

response.inspect 
# => #<Net::HTTPOK:0x007ff8bc7c1200>

response.body
# => {
#      "access_token" : "e409f4272fe539166a77c42479de030e7660812a",
#      "token_type" : "bearer"
#    }"
```

### Implicit Grant
```ruby
auth_url = yammer_client.clientside_authorization_url(:redirect_uri => 'http://localhost/oauth2/callback')
# => "https://www.yammer.com/dialog/oauth/?client_id=PRbTcg9qjgKsp4jjpm1pw&redirect_uri=http%3A%2F%2Flocalhost%2Foauth%2Fcallback&response_type=token"
```

# Using a custom Http wrapper
By default, yammer-oauth2 uses the `oauth2-client` gem's HTTP wrapper `OAuth2::HttpConnection`. However, if you wish to use a different HTTP library, you only
need to create a wrapper around your favorite library that will respond to the `send_request` method.

```ruby
class TyphoeusHttpConnection
  
  def initialize(site_url, connection_options={})
    # set url and connection options
    @site_url = site_url
    @connection_options = connection_options
  end

  def base_url(path)
    @site_url + path
  end

  def send_request(http_method, request_path, options={})
    # options may contain optional arguments like http headers, request parameters etc
    # send http request over the inter-webs

    params          = options[:params] || {}
    headers         = options[:headers]|| {}
    method          = method.to_sym
    client          = Typhoeus

    case method
    when :get, :delete
      #pass
    when :post, :put
      options[:body] = options.delete(:params) if options[:params]
    else
      raise UnhandledHTTPMethodError.new("Unsupported HTTP method, #{method}")
    end
    response = client.send(http_method, base_url(request_path), params)
  end
end

# now you can initialize the OAuth2 client with you custom client and expect that all requests
# will be sent using this client
oauth_client = YammerOAuth2::Client.new('example.com', client_id, client_secret, {
  :connection_client  => TyphoeusHttpConnection,
  :connection_options => { :use_ssl => true }
})
```

## Supported Ruby Versions
This library aims to support and is [tested against][travis] the following Ruby
version:

* Ruby 1.8.7
* Ruby 1.9.2
* Ruby 1.9.3

This library may inadvertently work (or seem to work) on other Ruby
implementations, however support will only be provided for the versions listed
above.

## Copyright
Copyright (c) 2013 Kevin Mutyaba
See [LICENSE][license] for details.
[license]: https://github.com/tiabas/yammer-oauth2/blob/master/LICENSE