yam 0.0.6 → 1.0.0

data/.travis.yml

@@ -1,9 +1,14 @@
 language: ruby
 rvm:
+  - 2.0.0
   - 1.9.3
   - 1.9.2
   - 1.8.7
   - ree
+  - rbx-19mode
+branches:
+  only:
+    - master
 before_install:
   - gem update --system
   - gem --version

data/.yardopts

@@ -0,0 +1,10 @@
+--no-private
+--protected
+--tag api_path:"Rest API path"
+--tag rate_limited:"Rate Limited?"
+--tag authentication:"Authentication"
+--markup markdown
+-
+CHANGELOG.md
+LICENSE.md
+README.md

data/AUTHORS

@@ -0,0 +1 @@
+* Kevin Mutyaba <kmutyaba@microsoft.com>

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+1.0.0
+====================================
+- Customized fork of yammer-client (https://github.com/tiabas/yammer-client)
+
+0.0.6
+====================================
+- Alpha

data/CONTRIBUTING.md

@@ -81,10 +81,3 @@ Syntax
 * Follow the conventions you see used in the source already.
 
 And in case we didn't emphasize it enough: we love tests!
-
-
-Development process
--------------------
-
-For details and screenshots of the feature branch code review process,
-read [this blog post](http://robots.thoughtbot.com/post/2831837714/feature-branch-code-reviews).

data/Gemfile

@@ -1,4 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright (c) Microsoft Corporation
+# All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY
+# IMPLIED WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR
+# PURPOSE, MERCHANTABLITY OR NON-INFRINGEMENT.
+#
+# See the Apache Version 2.0 License for specific language governing
+# permissions and limitations under the License.
+
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in yam.gemspec
+group :test do
+  # gem 'json', :platforms => :ruby_18
+  gem 'rspec', '>= 2.11'
+  gem 'simplecov', :require => false
+  gem 'coveralls', :require => false
+  gem 'webmock', '>= 1.10.1'
+end
+
 gemspec

data/README.md

@@ -1,14 +1,25 @@
 Yam
-===
+=============
+[![Gem Version](https://badge.fury.io/rb/yam.png)](http://badge.fury.io/rb/yam)
+[![Build Status](https://travis-ci.org/yammer/yam.png?branch=master)][travis]
+[![Coverage Status](https://coveralls.io/repos/yammer/yam/badge.png)](https://coveralls.io/r/yammer/yam)
 
-[![Build Status](https://api.travis-ci.org/yammer/yam.png)](https://travis-ci.org/yammer/yam)
+[gemversion]: (http://badge.fury.io/rb/yam)
+[travis]: (https://travis-ci.org/yammer/yam)
+[coveralls]: (https://coveralls.io/r/yammer/yam)
 
-The official Yammer Ruby gem.
+A Yammer Ruby gem
 
-NOTE: Currently in alpha - use at your own risk
+## Documentation
 
-Installation
-------------
+This README provides only a basic overview of how to use this gem.For more information about the API endpoints and helper methods available, look at the rdoc documentation.
+
+[http://rdoc.info/github/yammer/yam][documentation]
+
+[documentation]: http://rdoc.info/github/yammer/yam/index 
+
+
+## Installation
 
 Add this line to your application's Gemfile:
 
@@ -28,119 +39,231 @@ Or install it yourself as:
 $ gem install yam
 ```
 
-General Configuration
----------------------
+## Configuration
 
-The Yammer API requires you to authenticate via OAuth, so you'll need to register your Yammer application. To register a new application, sign in to Yammer and then fill out the form at https://www.yammer.com/client_applications.
+The Yammer API requires authentication for access to certain endpoints. Below are the basic steps to get this done.
 
-If you already have your access token, you can skip this section.
+### Register your application
 
-To retrieve your access token, follow these steps.
+Setup a Yammer client application as described in [Build your first Yammer App](https://developer.yammer.com/introduction/)
 
-1. Construct the following URL using the client_id you received after registering your app with Yammer: <https://www.yammer.com/dialog/oauth?client_id=[:client_id]>
+### Obtaining an access token
 
-2. Follow the URL you constructed above. It will take you to a Yammer OAuth dialog. Click the "Allow" button.
+1. Construct the following URL using the client_id you received `https://www.yammer.com/dialog/oauth?client_id=[:client_id]`
 
-3. You will be redirected to a URL that looks something like this: <http://[:redirect_uri]?code=[:code]>
+2. Have your users follow the URL you constructed above to allow your application to access their data 
 
-4. Use the code from step 3 along with your client_id and client_secret (obtained when registering your app) to construct the following URL:
-<https://www.yammer.com/oauth2/access_token.json?client_id=[:client_id]&client_secret=[:client_secret]&code=[:code]>
+3. After allowing access, your users will be redirected to your callback URL `http://[:redirect_uri]?code=[:code]`
 
-5. The authorization server will return an access token object as part of a broader response that includes user profile information.
+4. Exchange the code for an access token by making an HTTP GET request to `https://www.yammer.com/oauth2/access_token.json?client_id=[:client_id]&client_secret=[:client_secret]&code=[:code]`
 
-Sample access token (token is 'abcdefghijklmn' in this example) as part of response:
+5. The authorization server will respond with an access token
 
 ```
-“access_token”: {
-  “view_subscriptions”: true,
-  “expires_at”: null,
-  authorized_at”: “2011/04/06 16:25:46 +0000”,
-  “modify_subscriptions”: true,
-  “modify_messages”: true,
-  “network_permalink”: “yammer-inc.com”,
-  “view_members”: true,
-  “view_tags”: true,
-  “network_id”: 155465488,
-  “user_id”: 1014216,
-  “view_groups”: true,
-  “token”: “abcdefghijklmn”,
-  “network_name”: “Yammer”,
-  “view_messages”: true,
-  “created_at”: “2011/04/06 16:25:46 +0000”
+"access_token": {
+  "view_subscriptions": true,
+  "expires_at": null,
+  authorized_at": "2011/04/06 16:25:46 +0000",
+  "modify_subscriptions": true,
+  "modify_messages": true,
+  "network_permalink": "yammer-inc.com",
+  "view_members": true,
+  "view_tags": true,
+  "network_id": 155465488,
+  "user_id": 1014216,
+  "view_groups": true,
+  "token": "abcdefghijklmn",
+  "network_name": "Yammer",
+  "view_messages": true,
+  "created_at": "2011/04/06 16:25:46 +0000"
 }
 ```
 
-Set the OAuth token on your app. Example:
+### Configuring yammer-client
+
+To view the current state of the client use the `options` method
 
 ```ruby
-Yam.configure do |config|
-  config.oauth_token = your_oauth_token
+require 'yammer'
+
+Yammer.options
+#> {:site_url=>"https://www.yammer.com", :client_id=>nil, :client_secret=>nil, :access_token=>nil, :http_adapter=>Yammer::Connection, :connection_options=>{:max_redirects=>5, :use_ssl=>true}} 
+```
+
+You may change this configuration by using the `configure` method
+
+```ruby
+Yammer.configure do |c|
+  c.client_id = '[client_id]'
+  c.client_secret = '[client_secret]'
+  c.token = '[access_token]'
 end
+#> Yammer 
+```
+
+At this point, your new settings will take effect
+
+```ruby
+Yammer.options
+#> {:site_url=>"https://www.yammer.com", :client_id=>'[client_id]', :client_secret=>'[client_secret]', :access_token=>'[access_token]', :http_adapter=>Yammer::Connection, :connection_options=>{ :max_redirects=>5, :use_ssl=>true }} 
+```
+
+## Usage
+
+ `yammer-client` provides two ways to access Yammer's API. One of these ways is by using HTTP helper methods on and instance of `Yammer::Client`. The other 
+ way is using methods on the object models that come bundled with this gem.
+
+### Using the client
+
+1. Create an instance of the Yammer client
+
+```ruby
+yamr = Yammer::Client.new(
+        :client_id     => 'vAbMcg9qjgKsp4jjpm1pw',
+        :client_secret => 'Wn0kp7Lu0TCY4GtZWkmSsqGErg10DmMADyjWkf2U',
+        :access_token  => 'HqsKG3ka9Uls2DxahNi78A'
+      )
 ```
 
-Rails Configuration
--------------------
+2. Call methods on the instance:
 
-Retrieve your access token using the steps outlined in the <a href="#general-configuration">general configuration</a> section above.
+**User**
 
-Add the following to a `yammer.rb` file in your `config/initializers` directory:
+*find a user by email*
 
 ```ruby
-Yam.configure do |config|
-  config.oauth_token = oauth_token
-end
+yamr.get_user_by_email('user@example.com')
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
+```
+
+*find a user by user id*
+
+```ruby
+yamr.get_user('1588')
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
+```
+
+*get the current user*
+
+```ruby
+yamr.current_user
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
 ```
 
-Set up Yammer OAuth 2.0
------------------------
 
-See Yammer's Developer Guide for step-by-step instructions on setting up OAuth 2.0: <http://developer.yammer.com/files/2012/10/PlatformDeveloperGuide.pdf>
+**Message**
 
-Usage Examples
---------------
+*post a update as the current user*
 
-All examples require an authenticated Yammer client. See the <a
-href="#general-configuration">general configuration</a> section for instructions for finding and setting your access token.
+```ruby
+yamr.create_message('status update')
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
+```
+
+*send a private message to another Yammer user*
+
+```ruby
+yamr.create_message('private message', :direct_to_id => 24)
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
+```
+
+*send a message with an Open Graph Object as an attachment*
+
+```ruby
+yamr.create_message('here is my open graph object', :og_url => "https://www.yammer.com/example/graph/31415926")
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
+```
+
+
+**Search**
+
+*search for a term within the context of current user*
+
+```ruby
+yamr.search(:search => 'thekev', :model_types => 'users;groups')
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
+```
 
-For a list of all Yammer API endpoints, see the <a href="http://developer.yammer.com/restapi/">REST API documentation</a>.
+**Thread**
 
-**Find a Yammer user by email**
+*fetch a thread with a given id*
 
 ```ruby
-Yam.get('/users/by_email', email: 'user@example.com')
+yamr.get_thread(42)
+#<Yammer::ApiResponse:0x007fb949434ec8 @headers=#<Net::HTTPOK 200 OK readbody=true>, @body="[JSON Response]", @code=200>
 ```
 
-**Find a Yammer user by the Yammer user id**
+
+### Using the object models (Experimental)
+
+The object model is an abstraction that makes it easy to manipulate the JSON data return when accessing Yammer's API. Each model has accessor methods for all keys contained in the JSON response for a given model type. 
+
+
+**User**
+
+*get the current user*
+
 
 ```ruby
-Yam.get('/users/123456')
+u = Yammer::User.current
+#> <Yammer::User:0x007f9f4b0c39c8>
+
+u.full_name
+#> 'Kevin Mutyaba'
+
+u.update!(:job_title => 'k0dR')
 ```
 
-**Post a status update from the current user**
+
+**Thread**
+
+*fetch a thread with a given id*
 
 ```ruby
-Yam.post('/messages', body: 'status update')
+t = Yammer::Thread.get(3)
 ```
 
-**Send a private message to another Yammer user**
+View the participants in the thread
 
 ```ruby
-Yam.post('/messages', body: 'this is a private message', direct_to_id: 123456)
+parts = t.participants
+#> [{:type=>"user", :id=>18}, {:type=>"user", :id=>64}]
 ```
 
-**Send a private message to a Yammer group**
+View the participants in the thread as user object models
 
 ```ruby
-Yam.post('/messages', body: 'this is a group message', group_id: 987654)
+peepl = t.people
+#> [#<Yammer::User:0x007f9f4c086630 @modified_attributes={}, @attrs={}, @new_record=false, @id=18>, #<Yammer::User:0x007f9f4c086568 @modified_attributes={}, @attrs={}, @new_record=false, @id=64>] 
 ```
 
-**Send a message with an Open Graph Object as an attachment**
+Object models are lazyly loaded. Calling an accessor on a model will hydrate it
 
 ```ruby
-Yam.post('/messages', :body: 'here is my open graph object', og_url: "https://www.yammer.com/example/graph/123456789")
+peepl[0]
+#> #<Yammer::User:0x007f9f4c086568 @modified_attributes={}, @attrs={}, @new_record=false, @id=18> 
+
+peepl[0].permalink
+#> 'thekev'
+
+peepl[0]
+#=> #<Yammer::User:0x007f9f4c086568 @modified_attributes={}, @attrs={:last_name=>"Mutyaba", :network_id=>1, :first_name=>"Kevin", :id => 18,  :permalink=>"thekev" }, @network_id=1, @first_name="Kev", @full_name="Tiaba", @permalink="thekev", @id=18 > 
 ```
 
-Contributing
-------------
+## 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
+* Ruby 2.0.0
+
+This library may inadvertently work (or seem to work) on other Ruby
+implementations, however support will only be provided for the versions listed
+above.
 
-To contribute to this project, see the [CONTRIBUTING.md](https://github.com/yammer/yam/blob/master/CONTRIBUTING.md) file.
+## Copyright
+Copyright (c) 2013 Microsoft Corporation
+See [LICENSE][license] for details.
+[license]: https://github.com/tiabas/yammer-client/blob/master/LICENSE.md

data/Rakefile

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 # Copyright (c) Microsoft Corporation
 # All rights reserved.
 #
@@ -14,10 +16,14 @@
 #
 # See the Apache Version 2.0 License for specific language governing
 # permissions and limitations under the License.
-#
-require 'bundler/gem_tasks'
+
+require 'rake'
 require 'rspec/core/rake_task'
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = true
+end
 
+desc "Run spec"
 task :default => :spec
+task :test    => :spec

data/certs/public.pem

@@ -0,0 +1,20 @@
+-----BEGIN CERTIFICATE-----
+MIIDMjCCAhqgAwIBAgIBADANBgkqhkiG9w0BAQUFADA/MREwDwYDVQQDDAh0aWFi
+YXNuazEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPyLGQBGRYDY29t
+MB4XDTEzMDQyOTA0MTkwMFoXDTE0MDQyOTA0MTkwMFowPzERMA8GA1UEAwwIdGlh
+YmFzbmsxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkWA2Nv
+bTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMWly4vv32/qfYWuiRJq
+/x9CDRpdQ2JFwRiiKA6hjWjkpvYwgssfAVNJcwYSyVWkvRF8wp3UjpWqq+W3zGwR
+XHtKysmt8CZl7Y+JdcltSuaRuZljwN37RPnFg7gGHUfhS4klm6s8csvawLzi50eH
+6M/7AeKmYS7sRFQoVR0tfHxq+e5uqo47Qus+aLNFU/bgYJeAhZlYHeU0ANZIp3ig
+HRfYE3zz3CA+LffxQ0UXwiySLgUUsdX1Gtv/7AjoLu6v3GS0lbN9o357b0n7fXym
+A5iMUeygRZryvLab9kz1YuwgOgx6OpyQD8JfO9PZeBKYd9XFlZwp44W7Z1akxcu+
++E8CAwEAAaM5MDcwCQYDVR0TBAIwADAdBgNVHQ4EFgQUt6oHkpfViE/jN5InJLzl
+DUxUNR8wCwYDVR0PBAQDAgSwMA0GCSqGSIb3DQEBBQUAA4IBAQBunWeru+ZC1uVt
+BZj6230whZIvdvGnvcWW6JGG6JZJljYwOHHnaG+u74qE16Voh3n7rT77obp/Wrmx
+HUhp4nK+j1AHpdiZman0RxMZzS2fczev9gTyAs/cmaqgVb3YXXniwvZy4P7y07iT
+MIbAh4p4NK72MJrOsepD3qhOgE23o8dyFB3+RTB0U7yv3ZW1sMNDxkliqCBqcrBF
+bSEMaRUpbbsivejLXgRsxP5cXYy0Wd9GNSOtQ5932HDEoo0F9nXIMZGQSLqEXz3l
+B+kZ9/4dAvmKkr2NPSoxBQtO7Rz0HDNLtjMxkXbQUWMDsGnB6Kk1WUBb/w3kQ9Ah
+JgIHF4cG
+-----END CERTIFICATE-----