platforms-yammer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 772704cd07bae935f2988fda8cfb11dd803481e20c75efe12ade6db20c4f2f1b
+  data.tar.gz: 33c704d4e826872402bf47d242b8336d27fb249a81d4b7055dde320277977c27
+SHA512:
+  metadata.gz: c6ac0318074dfabecd5391679c31ebb2a9af3acd6ae11a473f228f5a6b7a1722e5ec287d3bce1edb776057e6ae3ae4b8512a61d71fb9560f4591dd7021dab6a2
+  data.tar.gz: 056d5f6d146b90959ae87ac75b437bee282d29eaeb5d325ee4cdfab3429337a60dac11bf6b92f7af7cd48468b31e8911832f3da8880a590f0524b83bec57fed8

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 Benjamin Elias
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# Platforms::Yammer
+
+This is an easy-to-use Ruby library which takes all the hard work out of writing a Yammer App.
+
+Platforms::Yammer supports all documented API endpoints, and has the flexibility of being able to call new, updated, or undocumented API endpoints too.
+
+## Usage
+
+This gem consists of two main parts. You need to have already [created an App](https://developer.yammer.com/docs/getting-started) in Yammer before using this gem.
+
+### 1. Authentication
+
+Assuming the "Redirect URI" for your App is `https://www.myapp.com/auth/yammer/callback`, in your routes file set that route to a controller of your choice. `SessionsController` is used in the examples below..
+
+```ruby
+# config/routes.rb
+
+Rails.application.routes.draw do
+  # ...
+  match '/auth/:provider/callback', to: 'sessions#callback', via: [:get, :post]
+  # ...
+end
+```
+
+In the Sessions controller, include the `Platforms::Yammer::Authentication` module and call `save_identity` in the `callback` method:
+
+```ruby
+# app/controllers/sessions_controller
+
+class SessionsController < ApplicationController
+  include Platforms::Yammer::Authentication
+
+  before_action :set_token
+
+  def callback
+    # ...
+    save_identity
+    # ...
+  end
+
+end
+```
+
+This will give you instance variables `@platforms_user`, `@platforms_network`, `@token`, and `@switch_network_ids`, giving you details of the Yammer user.
+Some of this information will be useful to store in a [session](https://guides.rubyonrails.org/security.html#session-storage).
+See {Platforms::Yammer::Authentication#save_identity} for more details.
+
+This callback method also has access to more detailed information about the logged-in user through `request.env[omniauth.auth']`. More information about the data that is stored in that variable can be found in the OmniAuth [Auth Hash Schema](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema) description.
+
+Switching between Yammer Networks is achieved through {Platforms::Yammer::Authentication#switch_identity}, which is treated as a regular API request.
+
+### 2. API Requests
+
+Use the `@token`, found during [Authentication](#authentication), to create a new {Platforms::Yammer::Client}. That client can then be used to make API requests.
+
+```ruby
+client = Platforms::Yammer::Client.new(@token)
+messages = client.messages.get
+```
+
+More detail on the configuration options for the {Platforms::Yammer::Client} can be found in the class documentation, including how to change the handling of HTTP errors.
+
+Extra request parameters and headers can generally be passed in the subsequent parameters to a method:
+
+```ruby
+messages = client.messages.get { :older_than => 123 }, { :custom => :header }
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'platforms-yammer'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install platforms-yammer
+```
+
+Once the gem is installed, from your Rails directory you can run the following generator to complete the installation:
+
+```bash
+$ rails generate platforms:yammer:install
+```
+
+This will:
+
+* Complete the installation of the [Platforms::Core](https://github.com/collabital/platforms-core) gem; and
+* Add a basic initializer to `config/initializers/platforms_yammer.rb`.
+
+## Configuration
+
+REST-based APIs require authentication to get started. Please refer to the Yammer documentation for how to configure an integration.
+
+### Configuring the Keys
+
+Edit the initializer to add the credentials of your Yammer integration:
+
+```ruby
+# config/initializers/platforms_yammer.rb
+
+```
+
+### Starting a New App
+
+Your application needs to have at least `Network` and `User` models. These can be created by calling the generator:
+
+```bash
+$ rails generate platforms:core:network foo some_info:string
+$ rails generate platforms:core:user bar user more_info:string
+$ rake db:migrate
+```
+
+Typically these would actually be called "Network" and "User", but here we have called them "Foo" and "Bar".
+
+For more detailed instructions, refer to the documentation for configuring [Platforms::Core](https://github.com/collabital/platforms-core#configuration).
+
+### Adding to an Existing App
+
+If you already have `Network` and `User` models (which let's assume are called "Foo" and "Bar" respectively), you can configure them for Platforms::Core by using the generator with the `--existing-model` flag:
+
+```bash
+$ rails generate platforms:core:network foo --existing-model
+$ rails generate platforms:core:user bar --existing-model
+$ rake db:migrate
+```
+
+For more detailed instructions, refer to the documentation for configuring [Platforms::Core](https://github.com/collabital/platforms-core#configuration).
+
+## Documentation
+
+You can generate the documentation by running
+
+```bash
+$ rake yard
+```
+
+If not everything is documented, check this with:
+```bash
+$ yard stats --list-undoc
+```
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+end
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+task :default => ["app:spec"]

data/lib/generators/platforms/yammer/install/USAGE

@@ -0,0 +1,11 @@
+Description:
+    This will install the required migrations, and set up initializers
+
+Example:
+    rails generate platforms:yammer:install
+
+    This will create:
+      The initializer in config/initializers/platforms_yammer.rb
+      Run $ rails generate platforms:core:install
+
+      Note that it will not run the migrations

data/lib/generators/platforms/yammer/install/install_generator.rb

@@ -0,0 +1,29 @@
+require 'rails/generators'
+
+module Platforms
+  module Yammer
+
+    # Simplify the installation of Platforms::Yammer by creating an
+    # initializer file and installing the migrations.
+    # This does not run the migrations.
+    # @author Benjamin Elias
+    # @since 0.1.0
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      # Create config/initializers/platforms_yammer.rb according
+      # to the template.
+      def copy_initializer_file
+        copy_file "platforms_yammer.rb", "config/initializers/platforms_yammer.rb"
+      end
+
+      # Install Platforms::Core.
+      # This uses the built in Rails generate method to call the
+      # other gem's installer.
+      def install_core
+        generate "platforms:core:install"
+      end
+
+    end
+  end
+end

data/lib/generators/platforms/yammer/install/templates/platforms_yammer.rb

@@ -0,0 +1,4 @@
+Platforms::Yammer.configure do |config|
+  config.client_id =     "your_client_id"
+  config.client_secret = "your_client_secret"
+end

data/lib/platforms/yammer.rb

@@ -0,0 +1,15 @@
+require "platforms/yammer/authentication"
+require "platforms/yammer/configuration"
+require "platforms/yammer/engine"
+require "platforms/yammer/railtie"
+require "platforms/yammer/client"
+
+require "generators/platforms/yammer/install/install_generator"
+
+# A flexible module to allow integrations with a number of enterprise social
+# and collaboration platforms with Rails.
+module Platforms
+  # A gem to build Yammer integrations with Rails
+  module Yammer
+  end
+end

data/lib/platforms/yammer/api.rb

@@ -0,0 +1,39 @@
+require "platforms/yammer/api/base"
+require "platforms/yammer/api/messages"
+require "platforms/yammer/api/pending_attachments"
+require "platforms/yammer/api/uploaded_files"
+require "platforms/yammer/api/threads"
+require "platforms/yammer/api/topics"
+require "platforms/yammer/api/group_memberships"
+require "platforms/yammer/api/groups"
+require "platforms/yammer/api/users"
+require "platforms/yammer/api/relationships"
+require "platforms/yammer/api/streams"
+require "platforms/yammer/api/suggestions"
+require "platforms/yammer/api/subscriptions"
+require "platforms/yammer/api/invitations"
+require "platforms/yammer/api/search"
+require "platforms/yammer/api/networks"
+require "platforms/yammer/api/open_graph_objects"
+require "platforms/yammer/api/oauth"
+require "platforms/yammer/api/supervisor_mode"
+
+module Platforms
+  module Yammer
+    # Module for all Yammer's API endpoints
+    #
+    # These are organised per-class in the 'directory' of the namespace.
+    # Methods are generally called 'get', 'post', and 'delete' for simple
+    # requests and named methods if more complex.
+    #
+    # For example:
+    # * {Messages#get} maps to GET /messages.json
+    # * {Messages#post} maps to POST /messages.json
+    # * {Messages#my_feed} maps to GET /messages/my_feed.json
+    #
+    # @author Benjamin Elias
+    # @since 0.1.0
+    module Api
+    end
+  end
+end

data/lib/platforms/yammer/api/base.rb

@@ -0,0 +1,20 @@
+module Platforms
+  module Yammer
+    module Api
+      # Base class taking care of common setup for Platforms::Yammer::Api
+      # classes.
+      # @author Benjamin Elias
+      # @since 0.1.0
+      class Base
+
+        # Initialize with a Faraday connection
+        # @param [Faraday::Connection] connection The connection to use
+        def initialize connection
+          @connection = connection
+        end
+
+      end
+    end
+  end
+end
+

data/lib/platforms/yammer/api/group_memberships.rb

@@ -0,0 +1,35 @@
+module Platforms
+  module Yammer
+    module Api
+      # Group memberships in Yammer
+      # @author Benjamin Elias
+      # @since 0.1.0
+      class GroupMemberships < Base
+
+        # Join a Group
+        # @param group_id [#to_s] The ID of the Group to join
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/group_membershipsjsongroup_idid
+        def post group_id, options={}, headers={}
+          body = options.merge({ group_id: group_id})
+          @connection.post 'group_memberships.json', body, headers
+        end
+
+        # Leave a Group
+        # @param group_id [#to_s] ID of Group to leave
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/group_membershipsjsongroup_idid-1
+        def delete group_id, options={}, headers={}
+          params = options.merge({group_id: group_id})
+          @connection.delete 'group_memberships.json', params, headers
+        end
+
+      end
+    end
+  end
+end
+

data/lib/platforms/yammer/api/groups.rb

@@ -0,0 +1,22 @@
+module Platforms
+  module Yammer
+    module Api
+      # Groups in Yammer
+      # @author Benjamin Elias
+      # @since 0.1.0
+      class Groups < Base
+
+        # Get group memberships for a user
+        # @param user_id [#to_s] The user to query for memberships
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/groupsfor_useruser_idjson
+        def for_user user_id, options={}, headers={}
+          @connection.get "groups/for_user/#{user_id}.json", options, headers
+        end
+      end
+    end
+  end
+end
+

data/lib/platforms/yammer/api/invitations.rb

@@ -0,0 +1,23 @@
+module Platforms
+  module Yammer
+    module Api
+      # Invite people to a Yammer network
+      # @author Benjamin Elias
+      # @since 0.1.0
+      class Invitations < Base
+
+        # Post invitations
+        # @param body [#to_s] Body of the request. Typically has email and may
+        # have group_id (optional).
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/invitationsjson
+        def post body=nil, headers={}
+          @connection.post "invitations.json", body, headers
+        end
+
+      end
+    end
+  end
+end
+

data/lib/platforms/yammer/api/messages.rb

@@ -0,0 +1,165 @@
+module Platforms
+  module Yammer
+    module Api
+      # Messaging endpoints for the Yammer API
+      # @author Benjamin Elias
+      # @since 0.1.0
+      class Messages < Base
+
+        # Get Messages from my feed
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesmy_feedjson
+        def my_feed options={}, headers={}
+          @connection.get "messages/my_feed.json", options, headers
+        end
+
+        # Get Messages through the algorithmic feed
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesalgojson
+        def algo options={}, headers={}
+          @connection.get "messages/algo.json", options, headers
+        end
+
+        # Get all messages
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesjson
+        def get options={}, headers={}
+          @connection.get "messages.json", options, headers
+        end
+
+        # Get messages in 'following' feed
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesfollowingjson
+        def following options={}, headers={}
+          @connection.get "messages/following.json", options, headers
+        end
+
+        # Sent messages
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagessentjson
+        def sent options={}, headers={}
+          @connection.get "messages/sent.json", options, headers
+        end
+
+        # Private messages
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesprivatejson
+        def private options={}, headers={}
+          @connection.get "messages/private.json", options, headers
+        end
+
+        # Received messages
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesreceivedjson
+        def received options={}, headers={}
+          @connection.get "messages/received.json", options, headers
+        end
+
+        # Messages in a thread
+        # @param thread_id [#to_s] The thread ID
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesin_threadthreadidjson
+        def in_thread thread_id, options={}, headers={}
+          @connection.get "messages/in_thread/#{thread_id}.json", options, headers
+        end
+
+        # Messages in a group
+        # @param group_id [#to_s] The group ID
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesin_groupgroup_id
+        def in_group group_id, options={}, headers={}
+          @connection.get "messages/in_group/#{group_id}.json", options, headers
+        end
+
+        # Messages about an Open Graph object
+        # @param id [#to_s] The Open Graph ID to filter by
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesopen_graph_objects
+        def open_graph_objects id, options={}, headers={}
+          @connection.get "messages/open_graph_objects/#{id}.json", options, headers
+        end
+
+        # Messages about a topic
+        # @param topic_id [#to_s] The topic to filter by
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesabout_topicidjson
+        def about_topic topic_id, options={}, headers={}
+          @connection.get "messages/about_topic/#{topic_id}.json", options, headers
+        end
+
+        # Post a new message
+        # @param body [#to_s] Body of the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messages-json-post
+        def post body, headers={}
+          @connection.post "messages.json", body, headers
+        end
+
+        # E-mail a copy of the message to the current user
+        # @param message_id [#to_s] The ID of the message to delete
+        # @param body [#to_s] Body of the request (should not need to be used)
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesemail
+        def email message_id, body=nil, headers={}
+          @connection.post "messages/email.json?message_id=#{message_id}", body, headers
+        end
+
+        # Like a message
+        # @param message_id [#to_s] The ID of the message to delete
+        # @param body [#to_s] Body of the request (should not need to be used)
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesliked_bycurrentjsonmessage_idid
+        def like message_id, body=nil, headers={}
+          @connection.post "messages/liked_by/current.json?message_id=#{message_id}", body, headers
+        end
+
+        # Unlike a message
+        # @param message_id [#to_s] The ID of the message to delete
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesliked_bycurrentjsonmessage_idid-1
+        def unlike message_id, options=nil, headers={}
+          @connection.delete "messages/liked_by/current.json?message_id=#{message_id}", options, headers
+        end
+
+        # Delete a message
+        # @param message_id [#to_s] The ID of the message to delete
+        # @param options [Hash] Options for the request
+        # @param headers [Hash] Additional headers to send with the request
+        # @return [Faraday::Response] the API response
+        # @see https://developer.yammer.com/docs/messagesid
+        def delete message_id, options=nil, headers={}
+          @connection.delete "messages/#{message_id}.json", options, headers
+        end
+
+      end
+    end
+  end
+end
+