intercom-app 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3b0feb331e88775fbb025a0935d5c6467714a300
-  data.tar.gz: 40506ec35b6b610b04438595eb8ee8e69b97ae8a
+  metadata.gz: b7f46437a2cf130cdd55c76cc0cd98308793834b
+  data.tar.gz: b3de97e1517c26d4e3b3283e3efce18d4ad56386
 SHA512:
-  metadata.gz: d914328e498bd9ed91be8d906e8217f43066b4f9fd3f75929427f63e4474e50cf478ca90318f0702698acdde2c206056ad34828ceea1baf2bfd274f4aa9272cc
-  data.tar.gz: 2de850e9d4740f6bb1159ba3aeb59c128414317e923d81601338ecf4938b5921ecad53f803ed1ef8dba0e54cbc18870e27f0200c0e026920da8f1843ce5f4694
+  metadata.gz: 4a49259db239d5a5c087a11c2f6144436deef5b9a61c117531c4fef9f7c416f2f6a3d3c847319e5de1f618cde01b0552116292ccad193464a9df1fcce5d384ad
+  data.tar.gz: a099e74a36e04a9eb83dc6860b11f187608b13169e5b6b47c6a46356cdb5f9313082e38c8389fe9271edca7938d5a2a06e0f4b38cf2b64e9a651be4f567a9a38

data/.gitignore

@@ -2,3 +2,4 @@
 test/intercom_ruby_app_example/log
 test/generators/tmp
 test/tmp
+todolist.md

data/CHANGELOG.md

@@ -23,3 +23,10 @@ Features:
 ## 0.2.1 (2016-08-17)
 
   * Fix webhook subscription fail (@Skaelv)
+
+## 0.2.2 (2016-10-11)
+
+    *  Add callback_hash Proc for custom storage
+    *  Add session_storage_on_login Proc for custom storage
+    *  Rename token to intercom_token
+    *  Allow custom storage to intercom App model (@Skaelv)

data/README.md

@@ -1,19 +1,19 @@
-Intercom App
+Intercom Integration
 ===========
 
 Intercom Application Rails engine and generator
 
-*Note this SDK is in beta version and still needs a lot of improvements. We advise you to use it only if you feel you can help contributing and fix issues when you find them*
-
 Description
 -----------
-This gem includes a Rails Engine and generators for writing Rails applications using the Intercom API. The Engine provides a SessionsController and all the required code for authenticating with an app via Oauth.
+This gem includes a Rails Engine and generators for writing Rails applications using the Intercom API. The Engine provides a SessionsController and all the required code for authenticating with an app via OAuth.
+
+[Getting started with Intercom Integrations](https://developers.intercom.io/docs/integration-setup-guide)
 
 Apply to become an Intercom Developer
 --------------------------------
-To create an Intercom application and get your `app_key` and `app_secret` you will need to create an [Intercom application](https://app.intercom.io) first.
-Once your application is created you can apply for an oauth application in the "App Settings >> Oauth" section.
-
+To create an Intercom application and get your `client_id` and `client_secret` you will need to create an [Intercom account](https://app.intercom.io) first.
+Once your application is created you can apply for an OAuth application in the "App Settings >> OAuth" section.
+Make sure you request read admin permission to use [omniauth-intercom](http://github.com/intercom/omniauth-intercom).
 Installation
 ------------
 To get started create a new rails app :
@@ -24,7 +24,7 @@ $ rails new my_intercom_app
 $ cd my_intercom_app
 ```
 Then add `intercom-app` to your Gemfile and bundle install :
-`gem 'intercom-app'`
+`gem 'intercom-app', '>= 0.2.1'`
 and run :
 ``` sh
 $ bundle install
@@ -41,7 +41,7 @@ Generators
 The default generator will run the `install`, `app_model`, and `home_controller` generators. This is the recommended way to start your app.
 
 ```sh
-$ rails generate intercom_app --app_key <your_app_key> --app_secret <your_app_secret> --oauth_modal true
+$ rails generate intercom_app --app_key <intercom_client_id> --app_secret <intercom_client_secret> --oauth_modal true
 ```
  **oauth_modal**:
    - If true you can authenticate with Intercom using a modal
@@ -50,6 +50,12 @@ $ rails generate intercom_app --app_key <your_app_key> --app_secret <your_app_se
 
 *Note that you will need to run rake db:migrate after this generator*
 
+At this point you've finished the setup. You can run `rails s` and complete Intercom Authentication to generate a new intercom_token.
+You can make calls to Intercom APIs using `@intercom_client` in all controllers that inherits from `IntercomApp::AuthenticatedController`. This `@intercom_client` variable is instantiated with the token associated to the current session.
+
+### Adding your own Intercom app to your Integration
+
+If you want to add Intercom's widget for your integration (which you definitely should!), we recommend that you configure [intercom-rails]("https://github.com/intercom/intercom-rails") independently.
 ### Install Generator
 
 ```sh
@@ -57,15 +63,15 @@ $ rails generate intercom_app:install
 
 # or optionally with arguments:
 
-$ rails generate intercom_app:install --app_key <your_app_key> --secret <your_app_secret> --oauth_modal true
+$ rails generate intercom_app:install --app_key <intercom_client_id> --app_secret <intercom_client_secret> --oauth_modal true
 ```
 
+*Note that you will need to run rake db:migrate after this generator*
+
 You can update any of these settings later on easily, the arguments are simply for convenience.
 
 The generator adds IntercomApp and the required initializers to the host Rails application.
 
-After running the `install` generator, you can start your app with `bundle exec rails server` and install your app by visiting localhost.
-
 
 ### App Model Generator
 
@@ -73,9 +79,9 @@ After running the `install` generator, you can start your app with `bundle exec
 $ rails generate intercom_app:app_model
 ```
 
-The install generator doesn't create any database models for you and if you are starting a new app its quite likely that you will want one (most of our internally developed apps do!). This generator creates a simple app model and a migration. It also creates a model called `SessionStorage` which interacts with `IntercomApp::SessionRepository`. Check out the later section to learn more about `IntercomApp::SessionRepository`
+The install generator doesn't create any database models for you and if you are starting a new app its quite likely that you will want one (most of our internally developed apps do!). This generator creates a simple `App` model and a migration. It also creates a model called `SessionStorage` which interacts with `IntercomApp::SessionRepository`. Check out the later section to learn more about `IntercomApp::SessionRepository`
+
 
-*Note that you will need to run rake db:migrate after this generator*
 
 
 ### Home Controller Generator
@@ -101,10 +107,51 @@ The `install` generator places your App credentials directly into the intercom_a
 IntercomApp.configure do |config|
   config.api_key = ENV['INTERCOM_CLIENT_APP_KEY']
   config.app_secret = ENV['INTERCOM_CLIENT_APP_SECRET']
+  config.hub_secret = ENV['INTERCOM_WEBHOOK_HUB_SECRET']
   config.oauth_modal = false
 end
 ```
 
+Session storage
+----------------------
+
+Configure the `store_in_session_before_login` Proc to store parameters in session before OAuth.
+```ruby
+IntercomApp.configure do |config|
+  # storing data in the session before the authentication helps you access them on the callback
+  # params contains omniauth hash (https://github.com/intercom/omniauth-intercom)
+  config.store_in_session_before_login = Proc.new do |session, params|
+      session[:name] = params[:name]
+      session[:third_party_admin_id] = params[:third_party_admin_id]
+    end
+  }
+end
+```
+
+
+Callback Storage
+----------------------
+
+When customers authenticate your app against Intercom, the OAuth `token` and the `intercom_app_id` are stored in the `App` model.
+To store custom data you simply need to add new attributes to `App` model by running a migration and configure the `callback_hash` Proc to return this custom data :
+
+```shell
+rails generate migration addNameAndThirdPartyAdminIdToApp
+```
+
+```ruby
+IntercomApp.configure do |config|
+  # retrieve previously stored in session params
+  # response contains omniauth hash (https://github.com/intercom/omniauth-intercom)
+  config.callback_hash = Proc.new { |session, response|
+    {
+      name: response[:name],
+      third_party_admin_id: session[:admin_id]
+    }
+  }
+end
+```
+
 Webhooks Subscriptions
 ----------------------
 
@@ -123,9 +170,31 @@ end
 **Important** You will need to request the `manage_webhooks` permissions from Intercom to receive webhooks from Intercom.
 
 
+Intercom-Wix
+----------------------
+
+The [intercom-wix](https://github.com/Skaelv/intercom-wix) app is an example of an integration generated with the `intercom-ruby-app`.
+
 Connect to the Intercom API
 ----------------------
 This gem includes the following libraries :
 
 http://github.com/intercom/omniauth-intercom <= Simple rake middleware to authenticate your customers with Intercom
 http://github.com/intercom/intercom-ruby <= Intercom Ruby API wrapper
+
+
+## Pull Requests
+
+- **Add tests!** Your patch won't be accepted if it doesn't have tests.
+
+- **Document any change in behaviour**. Make sure the README and any other
+  relevant documentation are kept up-to-date.
+
+- **Create topic branches**. Don't ask us to pull from your master branch.
+
+- **One pull request per feature**. If you want to do more than one thing, send
+  multiple pull requests.
+
+- **Send coherent history**. Make sure each individual commit in your pull
+  request is meaningful. If you had to make multiple intermediate commits while
+  developing, please squash them before sending them to us.

data/RELEASING

@@ -3,9 +3,9 @@ To release a new version of the intercom-ruby-app gem :
 2. Add a CHANGELOG entry
 3. Commit to master with an explicit message : "Bump to vX.Y.Z"
 4. Tag the new release :
-  $ git tag VX.Y.Z
+  $ git tag -a vx.y.z -m 'Tag message'
 5. Push the new release :
-  $ git push
+  $ git push origin master
 6. Push the new tag :
   $ git push --tags
 7. Build the new gem :

data/app/views/intercom_app/sessions/login.html.erb

@@ -19,5 +19,7 @@
   });
   </script>
 <% else %>
-  <a href="/auth/intercom">Login</a>
+  <a href="/auth/intercom">
+    <img src="https://static.intercomassets.com/assets/oauth/primary-7edb2ebce84c088063f4b86049747c3a.png" srcset="https://static.intercomassets.com/assets/oauth/primary-7edb2ebce84c088063f4b86049747c3a.png 1x, https://static.intercomassets.com/assets/oauth/primary@2x-0d69ca2141dfdfa0535634610be80994.png 2x, https://static.intercomassets.com/assets/oauth/primary@3x-788ed3c44d63a6aec3927285e920f542.png 3x"/>
+  </a>
 <% end %>

data/lib/generators/intercom_app/home_controller/templates/home_controller.rb

@@ -1,6 +1,8 @@
 class HomeController < IntercomApp::AuthenticatedController
 
   def index
-    @users_names = @intercom_client.users.find_all(:type=>'users', :per_page => 10, :page => 1, :order => "desc", :sort => "created_at").map(&:name)
+    # Example of an API request using intercom-ruby gem
+    # Request 'read users' permission for the following request
+    # @users_names = @intercom_client.users.find_all(:type=>'users', :per_page => 10, :page => 1, :order => "desc", :sort => "created_at").map(&:name)
   end
 end

data/lib/generators/intercom_app/home_controller/templates/index.html.erb

@@ -1,8 +1,10 @@
-<a href="/login">Login</a>
+<a href="/auth/intercom">
+  <img src="https://static.intercomassets.com/assets/oauth/primary-7edb2ebce84c088063f4b86049747c3a.png" srcset="https://static.intercomassets.com/assets/oauth/primary-7edb2ebce84c088063f4b86049747c3a.png 1x, https://static.intercomassets.com/assets/oauth/primary@2x-0d69ca2141dfdfa0535634610be80994.png 2x, https://static.intercomassets.com/assets/oauth/primary@3x-788ed3c44d63a6aec3927285e920f542.png 3x"/>
+</a>
 <h1>Intercom application</h1>
-<h2>Users list:</h2>
+<!-- <h2>Users list:</h2>
 <ul>
 <% @users_names.each do | name | %>
      <li> <%= name %></li>
-<% end %>
+<% end %> -->
 </ul>

data/lib/intercom-app/configuration.rb

@@ -6,6 +6,8 @@ module IntercomApp
     attr_accessor :oauth_modal
     attr_accessor :webhooks
     attr_accessor :hub_secret
+    attr_accessor :callback_hash
+    attr_accessor :store_in_session_before_login
 
     def initialize
     end

data/lib/intercom-app/login_protection.rb

@@ -9,7 +9,7 @@ module IntercomApp
     def intercom_session
       if app_session
         begin
-          @intercom_client = Intercom::Client.new(token: app_session[:token])
+          @intercom_client = Intercom::Client.new(token: app_session[:intercom_token])
           yield
         end
       else

data/lib/intercom-app/session_storage.rb

@@ -5,7 +5,7 @@ module IntercomApp
     class_methods do
       def store(sess)
         app = self.find_or_initialize_by(intercom_app_id: sess[:intercom_app_id])
-        app.intercom_token = sess[:token]
+        sess.each {|k,v| app[k] = v}
         app.save!
         app.id
       end
@@ -13,11 +13,9 @@ module IntercomApp
       def retrieve(id)
         return unless id
         if app = self.find_by(id: id)
-          session = {
-            id: app.id,
-            intercom_app_id: app.intercom_app_id,
-            token: app.intercom_token
-          }
+          session = {}
+          app.instance_variables{|k| session[k] = app[k]}
+          session
         end
       end
     end

data/lib/intercom-app/sessions_concern.rb

@@ -6,15 +6,22 @@ module IntercomApp
       include IntercomApp::LoginProtection
     end
 
+    def login
+      store_in_session_before_login.call(session, params) if store_in_session_before_login
+    end
+
     def callback
       if response = request.env['omniauth.auth']
         app = {
-          token: response['credentials']['token'],
-          intercom_app_id: response['extra']['raw_info']['app']['id_code']
+          intercom_token: response['credentials']['token'],
+          intercom_app_id: response['extra']['raw_info']['app']['id_code'],
+          name: response['extra']['raw_info']['name'],
+          email: response['extra']['raw_info']['email']
         }
+        app = app.merge(callback_hash.call(session, response)) if callback_hash
         session[:intercom] = IntercomApp::SessionRepository.store(app)
         session[:intercom_app_id] = app[:intercom_app_id]
-        IntercomApp::WebhooksManager.new(intercom_token: app[:token]).create_webhooks_subscriptions if IntercomApp.configuration.webhooks.present?
+        IntercomApp::WebhooksManager.new(intercom_token: app[:intercom_token]).create_webhooks_subscriptions if IntercomApp.configuration.webhooks.present?
         redirect_to return_address unless IntercomApp.configuration.oauth_modal
       else
         redirect_to login_url
@@ -24,6 +31,7 @@ module IntercomApp
     def destroy
       session[:intercom] = nil
       session[:intercom_app_id] = nil
+      session[:intercom_token] = nil
       redirect_to login_url
     end
 
@@ -32,5 +40,12 @@ module IntercomApp
       session.delete(:return_to) || '/'
     end
 
+    def callback_hash
+      IntercomApp.configuration.callback_hash
+    end
+
+    def store_in_session_before_login
+      IntercomApp.configuration.store_in_session_before_login
+    end
   end
 end

data/lib/intercom-app/version.rb

@@ -1,3 +1,3 @@
 module IntercomApp
-  VERSION = '0.2.1'
+  VERSION = '0.2.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: intercom-app
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Kevin Antoine
@@ -195,8 +195,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.1
 signing_key: 
 specification_version: 4
 summary: Intercom.io ruby application boilerplate
 test_files: []
+has_rdoc: