flowdock 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24e1cb19dbf59f9a6e46d8bd350acba328186ceb
-  data.tar.gz: 1e4a0a89662cf13e4f7f2d494450b356942bb6e6
+  metadata.gz: f1b21f2284092dd5c694e22637cd1f00bb85df48
+  data.tar.gz: ef80fc3c8718925b0efdcb7e2dadb6a6da8ffc85
 SHA512:
-  metadata.gz: 892e801cc9d9fa275bad3809f7bdf69fd90060b9f27701c9ffc50fb33c798a688c8d08a6c976439f1aa9a04f94e5780fbaa6deb38eee95603172dbeccfa64485
-  data.tar.gz: ae229181dfcebb6c491d42d80181e12dc32a8e96b8122bb58e8f34c744d0ffc5253fefdee099b57890b0d8e5a9763661840b415973f0d43357b4104d8c03bd39
+  metadata.gz: 38b75fa2a1bbeb1e912507c5672dec632601a8790e354029c00978b7e1564c678fb991b117cfcd62e3aa1d3ddec37c1f93f5101d8ae6abe302eaee1b4bf4cf23
+  data.tar.gz: a3f11ccf01ea48600d1208dbef5709ebc68fe8e3d36844d300f0f0e9adc7d984dc43da0d6686d2f826d3c260d2c2cc8062d7705b42bec0a4316d924ef06d0fb8

data/README.md

@@ -21,9 +21,65 @@ If you're using JRuby, you'll also need to install jruby-openssl gem.
 
 ## Usage
 
-To post content to Chat or Team Inbox, you need to use the target flow's API token. They can be found from [tokens page](https://www.flowdock.com/account/tokens).
+To post content to Chat or Team Inbox using `Flowdock::Flow`, you need to use the target flow's API token.
 
-### Posting to Chat
+Alternatively you can use your personal api token and the `Flowdock::Client`.
+
+All tokens can be found in [tokens page](https://www.flowdock.com/account/tokens).
+
+### REST API
+
+To create an api client you need your personal api token:
+
+```ruby
+require 'rubygems'
+require 'flowdock'
+
+# Create a client that uses you api token to authenticate
+client = Flowdock::Client.new(api_token: '__MY_PERSONAL_API_TOKEN__')
+```
+
+#### Posting to Chat
+
+To send a chat message or comment, you can use the client.chat_message:
+
+```ruby
+flow_id = 'acdcabbacd0123456789'
+
+# Send a simple chat message
+client.chat_message(flow: flow_id, content: "I'm sending a message!", tags: ['foo', 'bar'])
+
+# Send a comment to message 1234
+client.chat_message(flow: flow_id, content: "Now I'm commenting!", message: 1234)
+```
+
+Both methods return the created message as a hash.
+
+#### Arbitary api access
+
+You can use the client to access api in other ways too. See [REST API documentation](http://www.flowdock.com/api/rest) for all the resources.
+
+```ruby
+
+# Fetch all my flows
+flows = client.get('/flows')
+
+# Update a flow's name
+client.put('/flows/acme/my_flow', name: 'Your flow')
+
+# Delete a message
+client.delete('/flows/acme/my_flow/messages/12345')
+
+# Create an invitation
+client.post('/flows/acme/my_flow/invitations', email: 'user@example.com', message: "I'm inviting you to our flow using api.")
+
+```
+
+### Push api
+
+To use the push api, you need a flow token:
+
+#### Posting to Chat
 
 ```ruby
 require 'rubygems'
@@ -36,7 +92,7 @@ flow = Flowdock::Flow.new(:api_token => "__FLOW_TOKEN__", :external_user_name =>
 flow.push_to_chat(:content => "Hello!", :tags => ["cool", "stuff"])
 ```
 
-### Posting to Team Inbox
+#### Posting to Team Inbox
 
 ```ruby
 # create a new Flow object with target flow's api token and sender information for Team Inbox posting
@@ -49,7 +105,7 @@ flow.push_to_team_inbox(:subject => "Greetings from Flowdock API Gem!",
   :tags => ["cool", "stuff"], :link => "http://www.flowdock.com/")
 ```
 
-### Posting to multiple flows
+#### Posting to multiple flows
 
 ```ruby
 require 'rubygems'
@@ -63,7 +119,7 @@ flow = Flowdock::Flow.new(:api_token => ["__FLOW_TOKEN__", "__ANOTHER_FLOW_TOKEN
 
 ## API methods
 
-* Flow methods
+* `Flowdock::Flow` methods
 
   `push_to_team_inbox` - Send message to Team Inbox. See [API documentation](http://www.flowdock.com/api/team-inbox) for details.
 
@@ -71,6 +127,11 @@ flow = Flowdock::Flow.new(:api_token => ["__FLOW_TOKEN__", "__ANOTHER_FLOW_TOKEN
 
   `send_message(params)` - Deprecated. Please use `push_to_team_inbox` instead.
 
+* `Flowdock::Client` methods
+
+  `chat_message` - Send message to Chat.
+
+  `post`, `get`, `put`, `delete` - Send arbitary api calls. First parameter is the path, second is data. See [REST API documentation](http://www.flowdock.com/api/rest).
 
 ## Deployment notifications
 

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

data/flowdock.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: flowdock 0.4.0 ruby lib
+# stub: flowdock 0.5.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "flowdock"
-  s.version = "0.4.0"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Antti Pitk\u{e4}nen"]
-  s.date = "2014-04-10"
+  s.date = "2014-09-23"
   s.email = "team@flowdock.com"
   s.extra_rdoc_files = [
     "LICENSE",

data/lib/flowdock.rb

@@ -5,11 +5,29 @@ require 'multi_json'
 module Flowdock
   FLOWDOCK_API_URL = "https://api.flowdock.com/v1"
 
+  class InvalidParameterError < StandardError; end
+  class ApiError < StandardError; end
+
+  module Helpers
+    def blank?(var)
+      var.nil? || var.respond_to?(:length) && var.length == 0
+    end
+
+    def handle_response(resp)
+      json = MultiJson.decode(resp.body || '{}')
+      unless resp.code >= 200 && resp.code < 300
+        errors = json["errors"].map {|k,v| "#{k}: #{v.join(',')}"}.join("\n") unless json["errors"].nil?
+        raise ApiError, "Flowdock API returned error:\nStatus: #{resp.code}\n Message: #{json["message"]}\n Errors:\n#{errors}"
+      end
+      json
+    rescue MultiJson::DecodeError
+      raise ApiError, "Flowdock API returned error:\nStatus: #{resp.code}\nBody: #{resp.body}"
+    end
+  end
+
   class Flow
     include HTTParty
-    class InvalidParameterError < StandardError; end
-    class ApiError < StandardError; end
-
+    include Helpers
     attr_reader :api_token, :source, :project, :from, :external_user_name
 
     # Required options keys: :api_token
@@ -77,12 +95,16 @@ module Flowdock
 
       tags = (params[:tags].kind_of?(Array)) ? params[:tags] : []
       tags.reject! { |tag| !tag.kind_of?(String) || blank?(tag) }
+      thread_id = params[:thread_id]
+      message_id = params[:message_id] || params[:message]
 
       params = {
         :content => params[:content],
         :external_user_name => @external_user_name
       }
       params[:tags] = tags.join(",") if tags.size > 0
+      params[:thread_id] = thread_id if thread_id
+      params[:message_id] = message_id if message_id
 
       # Send the request
       resp = self.class.post(get_flowdock_api_url("messages/chat"), :body => params)
@@ -98,25 +120,62 @@ module Flowdock
 
     private
 
-    def blank?(var)
-      var.nil? || var.respond_to?(:length) && var.length == 0
+    def get_flowdock_api_url(path)
+      "#{FLOWDOCK_API_URL}/#{path}/#{@api_token}"
     end
 
-    def handle_response(resp)
-      unless resp.code == 200
-        begin
-          # should have JSON response
-          json = MultiJson.decode(resp.body)
-          errors = json["errors"].map {|k,v| "#{k}: #{v.join(',')}"}.join("\n") unless json["errors"].nil?
-          raise ApiError, "Flowdock API returned error:\nStatus: #{resp.code}\n Message: #{json["message"]}\n Errors:\n#{errors}"
-        rescue MultiJson::DecodeError
-          raise ApiError, "Flowdock API returned error:\nStatus: #{resp.code}\nBody: #{resp.body}"
-        end
-      end
+  end
+
+  class Client
+    include HTTParty
+    include Helpers
+    attr_reader :api_token
+    def initialize(options = {})
+      @api_token = options[:api_token]
+      raise InvalidParameterError, "Client must have :api_token attribute" if blank?(@api_token)
     end
 
-    def get_flowdock_api_url(path)
-      "#{FLOWDOCK_API_URL}/#{path}/#{@api_token}"
+    def chat_message(params)
+      raise InvalidParameterError, "Message must have :content" if blank?(params[:content])
+      raise InvalidParameterError, "Message must have :flow" if blank?(params[:flow])
+      params = params.clone
+      tags = (params[:tags].kind_of?(Array)) ? params[:tags] : []
+      params[:message] = params.delete(:message_id) if params[:message_id]
+      tags.reject! { |tag| !tag.kind_of?(String) || blank?(tag) }
+      event = if params[:message] then 'comment' else 'message' end
+      post(event + 's', params.merge(tags: tags, event: event))
+    end
+
+    def post(path, data = {})
+      resp = self.class.post(api_url(path), :body => MultiJson.dump(data), :basic_auth => {:username => @api_token, :password => ''}, :headers => headers)
+      handle_response(resp)
+    end
+
+    def get(path, data = {})
+      resp = self.class.get(api_url(path), :query => data, :basic_auth => {:username => @api_token, :password => ''}, :headers => headers)
+      handle_response(resp)
+    end
+
+    def put(path, data = {})
+      resp = self.class.put(api_url(path), :body => MultiJson.dump(data), :basic_auth => {:username => @api_token, :password => ''}, :headers => headers)
+      handle_response(resp)
+    end
+
+    def delete(path)
+      resp = self.class.delete(api_url(path), :basic_auth => {:username => @api_token, :password => ''}, :headers => headers)
+      handle_response(resp)
+    end
+
+    private
+
+    def api_url(path)
+      File.join(FLOWDOCK_API_URL, path)
+    end
+
+    def headers
+      {"Content-Type" => "application/json", "Accept" => "application/json"}
     end
   end
+
+
 end

data/spec/flowdock_spec.rb

@@ -11,7 +11,7 @@ describe Flowdock do
     it "should fail without token" do
       lambda {
         @flow = Flowdock::Flow.new(:api_token => "")
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should succeed with array of tokens" do
@@ -36,46 +36,46 @@ describe Flowdock do
       lambda {
         @flow = Flowdock::Flow.new(@flow_attributes.merge(:source => ""))
         @flow.push_to_team_inbox(@valid_attributes)
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should not send when source is not alphanumeric" do
       lambda {
         @flow = Flowdock::Flow.new(@flow_attributes.merge(:source => "$foobar"))
         @flow.push_to_team_inbox(@valid_attributes)
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should not send when project is not alphanumeric" do
       lambda {
         @flow = Flowdock::Flow.new(:api_token => "test", :source => "myapp", :project => "$foobar")
         @flow.push_to_team_inbox(@valid_attributes)
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should not send without sender information" do
       lambda {
         @flow = Flowdock::Flow.new(@flow_attributes.merge(:from => nil))
         @flow.push_to_team_inbox(@valid_attributes)
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should not send without subject" do
       lambda {
         @flow.push_to_team_inbox(@valid_attributes.merge(:subject => ""))
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should not send without content" do
       lambda {
         @flow.push_to_team_inbox(@valid_attributes.merge(:content => ""))
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should send without reply_to address" do
       lambda {
         @flow.push_to_team_inbox(@valid_attributes.merge(:reply_to => ""))
-      }.should_not raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should_not raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should succeed with correct token, source and sender information" do
@@ -221,7 +221,7 @@ describe Flowdock do
           to_return(:body => "Internal Server Error", :status => 500)
 
         @flow.push_to_team_inbox(:subject => "Hello World", :content => @example_content).should be_false
-      }.should raise_error(Flowdock::Flow::ApiError)
+      }.should raise_error(Flowdock::ApiError)
     end
   end
 
@@ -235,19 +235,19 @@ describe Flowdock do
     it "should not send without content" do
       lambda {
         @flow.push_to_chat(@valid_parameters.merge(:content => ""))
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should not send without external_user_name" do
       lambda {
         @flow.push_to_chat(@valid_parameters.merge(:external_user_name => ""))
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should not send with invalid external_user_name" do
       lambda {
         @flow.push_to_chat(@valid_parameters.merge(:external_user_name => "foo bar"))
-      }.should raise_error(Flowdock::Flow::InvalidParameterError)
+      }.should raise_error(Flowdock::InvalidParameterError)
     end
 
     it "should send with valid parameters and return true" do
@@ -290,7 +290,29 @@ describe Flowdock do
             :status => 400)
 
         @flow.push_to_chat(@valid_parameters).should be_false
-      }.should raise_error(Flowdock::Flow::ApiError)
+      }.should raise_error(Flowdock::ApiError)
+    end
+
+    it "should send supplied message to create comments" do
+      lambda {
+        stub_request(:post, push_to_chat_url(@token)).
+          with(:body => /message_id=12345/).
+          to_return(:body => "", :status => 200)
+
+        @flow = Flowdock::Flow.new(:api_token => @token, :external_user_name => "foobar")
+        @flow.push_to_chat(@valid_parameters.merge(:message_id => 12345))
+      }.should_not raise_error
+    end
+
+    it "should send supplied thread_id to post to threads" do
+      lambda {
+        stub_request(:post, push_to_chat_url(@token)).
+          with(:body => /thread_id=acdcabbacd/).
+          to_return(:body => "", :status => 200)
+
+        @flow = Flowdock::Flow.new(:api_token => @token, :external_user_name => "foobar")
+        @flow.push_to_chat(@valid_parameters.merge(:thread_id => 'acdcabbacd'))
+      }.should_not raise_error
     end
   end
 
@@ -310,3 +332,104 @@ describe Flowdock do
     end
   end
 end
+
+describe Flowdock::Client do
+
+  let(:token) { SecureRandom.hex(8) }
+  let(:client) { Flowdock::Client.new(api_token: token) }
+
+  describe 'initializing' do
+
+    it 'should initialize with access token' do
+      expect {
+        client = Flowdock::Client.new(api_token: token)
+        expect(client.api_token).to equal(token)
+      }.not_to raise_error
+    end
+    it 'should raise error if initialized without access token' do
+      expect {
+        client = Flowdock::Client.new(api_token: nil)
+      }.to raise_error(Flowdock::InvalidParameterError)
+    end
+  end
+
+  describe 'posting to chat' do
+
+    let(:flow) { SecureRandom.hex(8) }
+
+    it 'posts to /messages' do
+      expect {
+        stub_request(:post, "https://#{token}:@api.flowdock.com/v1/messages").
+          with(:body => MultiJson.dump(flow: flow, content: "foobar", tags: [], event: "message"), :headers => {"Accept" => "application/json", "Content-Type" => "application/json"}).
+          to_return(:status => 201, :body => '{"id":123}', :headers => {"Content-Type" => "application/json"})
+        res = client.chat_message(flow: flow, content: 'foobar')
+        expect(res).to eq({"id" => 123})
+      }.not_to raise_error
+    end
+    it 'posts to /comments' do
+      expect {
+        stub_request(:post, "https://#{token}:@api.flowdock.com/v1/comments").
+          with(:body => MultiJson.dump(flow: flow, content: "foobar", message: 12345, tags: [], event: "comment"), :headers => {"Accept" => "application/json", "Content-Type" => "application/json"}).
+          to_return(:status => 201, :body => '{"id":1234}', :headers => {"Content-Type" => "application/json"})
+        res = client.chat_message(flow: flow, content: 'foobar', message: 12345)
+        expect(res).to eq({"id" => 1234})
+      }.not_to raise_error
+    end
+    it 'raises without flow' do
+      expect {
+        client.chat_message(content: 'foobar')
+      }.to raise_error(Flowdock::InvalidParameterError)
+    end
+    it 'raises without content' do
+      expect {
+        client.chat_message(flow: flow)
+      }.to raise_error(Flowdock::InvalidParameterError)
+    end
+    it 'handles error responses' do
+      expect {
+        stub_request(:post, "https://#{token}:@api.flowdock.com/v1/messages").
+          to_return(:body => '{"message":"Validation error","errors":{"content":["can\'t be blank"],"external_user_name":["should not contain whitespace"]}}',
+            :status => 400)
+          client.chat_message(flow: flow, content: 'foobar')
+      }.to raise_error(Flowdock::ApiError)
+    end
+  end
+
+  describe 'GET' do
+    it 'does abstract get with params' do
+      stub_request(:get, "https://#{token}:@api.flowdock.com/v1/some_path?sort_by=date").
+         with(:headers => {'Accept'=>'application/json', 'Content-Type'=>'application/json'}).
+         to_return(:status => 200, :body => '{"id": 123}', :headers => {"Content-Type" => "application/json"})
+      expect(client.get('/some_path', {sort_by: 'date'})).to eq({"id" => 123})
+    end
+  end
+
+  describe 'POST' do
+    it 'does abstract post with body' do
+      stub_request(:post, "https://#{token}:@api.flowdock.com/v1/other_path").
+         with(:headers => {'Accept'=>'application/json', 'Content-Type'=>'application/json'}, :body => MultiJson.dump(name: 'foobar')).
+         to_return(:status => 200, :body => '{"id": 123,"name": "foobar"}', :headers => {"Content-Type" => "application/json"})
+      expect(client.post('other_path', {name: 'foobar'})).to eq({"id" => 123, "name" => "foobar"})
+    end
+
+  end
+
+  describe 'PUT' do
+    it 'does abstract put with body' do
+      stub_request(:put, "https://#{token}:@api.flowdock.com/v1/other_path").
+         with(:headers => {'Accept'=>'application/json', 'Content-Type'=>'application/json'}, :body => MultiJson.dump(name: 'foobar')).
+         to_return(:status => 200, :body => '{"id": 123,"name": "foobar"}', :headers => {"Content-Type" => "application/json"})
+      expect(client.put('other_path', {name: 'foobar'})).to eq({"id" => 123, "name" => "foobar"})
+    end
+  end
+
+  describe 'DELETE' do
+    it 'does abstract delete with params' do
+      stub_request(:delete, "https://#{token}:@api.flowdock.com/v1/some_path").
+         with(:headers => {'Accept'=>'application/json', 'Content-Type'=>'application/json'}).
+         to_return(:status => 200, :body => '', :headers => {"Content-Type" => "application/json"})
+      expect(client.delete('/some_path')).to eq({})
+    end
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flowdock
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Antti Pitkänen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-10 00:00:00.000000000 Z
+date: 2014-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty