chatwork 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f74e386e6cd2bfdb296f318244c848833efe5281661a70fd5f2b25997e5bbcc
-  data.tar.gz: ec96eec7324daf0413443dbae362119ed08191b89627269fdc5a757313a829c5
+  metadata.gz: 301622474ab7870e4bc7b6d51888c6af0f16224de722f865925b180ac8aa55b5
+  data.tar.gz: 745b6eaae10a5911cfd14ea8e53d587e8891e41e803fae50ba6ba502bb3b481c
 SHA512:
-  metadata.gz: cade7059d99ac62bb9245a8f0089007605fb0f29f887c4bfa7947165180649388cfc1466dd760491023feb523584fedc0a4288d5d4f4b252d5e5e63c81374ebd
-  data.tar.gz: 0e7b226006c9a84f650139ca991b2eebfda2576f6cad148da5b8fde20deceba3d00fd07de10d18588b2913c09384661e05d65e4b5149b2bfb886ac956a9aa651
+  metadata.gz: 6d3b4a9e19b02158ca9939980ab02e2f5665a98d5d004b8d63d4f2eda7e76eacddf253c1ef1c16cb17b24780bce853c04814bd3dd98763c372148fd777ca89dd
+  data.tar.gz: 0e65991b921fb0e541a50c2aa6cc92ac700ebcde31539bc8a562cb47d244956790f0dec64c033717fc87ca2315ef8c135fd42461d531c9a1353059357c494b58

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Change Log
 ## Unreleased
-[Full Changelog](https://github.com/asonas/chatwork-ruby/compare/v0.7.0...master)
+[Full Changelog](https://github.com/asonas/chatwork-ruby/compare/v0.8.0...master)
+
+## v0.8.0
+[Full Changelog](https://github.com/asonas/chatwork-ruby/compare/v0.7.0...v0.8.0)
+
+* Add instance methods of `ChatWork::Client`
+  * https://github.com/asonas/chatwork-ruby/pull/49
+* Fixed. API method did not accept block
+  * https://github.com/asonas/chatwork-ruby/pull/50
 
 ## v0.7.0
 [Full Changelog](https://github.com/asonas/chatwork-ruby/compare/v0.6.2...v0.7.0)

data/README.md

@@ -22,50 +22,45 @@ Or install it yourself as:
     $ gem install chatwork
 
 ## Usage
+`chatwork` gem provides class method APIs and instance method APIs
 
-### Case 1. with API Key
+### Class method APIs
+At first, set `ChatWork.api_key` or `ChatWork.access_token`.
 
-``` ruby
-require "chatwork"
-
-# Create message
+```ruby
 ChatWork.api_key = "XXX"
-ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
+# or
+ChatWork.access_token = "XXX"
 ```
 
-or
-
-``` sh
-$ cat send_message.rb
-require "chatwork"
+Another way, you can use `ENV["CHATWORK_API_TOKEN"]` or `ENV["CHATWORK_ACCESS_TOKEN"]` instead of `ChatWork.api_key` or `ChatWork.access_token`.
 
-ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
-$ CHATWORK_API_TOKEN=xxx ruby send_message.rb
-```
+Then call class methods.
 
-### Case 2. with OAuth access token
-``` ruby
-require "chatwork"
+e.g. post message.
 
-# Create message
-ChatWork.access_token = "XXX"
+```ruby
 ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
+#=> #<Hashie::Mash message_id="1234567890">
 ```
 
-or
-
-``` sh
-$ cat send_message_with_access_token.rb
-require "chatwork"
+All available APIs are followings.
 
-ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
-$ CHATWORK_ACCESS_TOKEN=xxx ruby send_message_with_access_token.rb
-```
+* [ChatWork::Contacts](lib/chatwork/contacts.rb)
+* [ChatWork::File](lib/chatwork/file.rb)
+* [ChatWork::IncomingRequest](lib/chatwork/incoming_request.rb)
+* [ChatWork::InvitationLink](lib/chatwork/invitation_link.rb)
+* [ChatWork::Me](lib/chatwork/me.rb)
+* [ChatWork::Member](lib/chatwork/member.rb)
+* [ChatWork::Message](lib/chatwork/message.rb)
+* [ChatWork::MyStatus](lib/chatwork/my_status.rb)
+* [ChatWork::MyTask](lib/chatwork/my_task.rb)
+* [ChatWork::Room](lib/chatwork/room.rb)
+* [ChatWork::Task](lib/chatwork/task.rb)
 
-### Case 3. Refresh access token with refresh token
-``` ruby
-require "chatwork"
+When you want to refresh access token, call [`ChatWork::Token.refresh_access_token`](lib/chatwork/token.rb).
 
+```ruby
 ChatWork.client_id = "XXX"
 ChatWork.client_secret = "XXX"
 refresh_token = "XXX"
@@ -77,19 +72,99 @@ ChatWork.access_token = new_access_token
 ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
 ```
 
-or
+Another way, you can use `ENV["CHATWORK_CLIENT_ID"]` or `ENV["CHATWORK_CLIENT_SECRET"]` instead of `ChatWork.api_key` or `ChatWork.access_token`.
+
+### Instance method APIs
+```ruby
+client = ChatWork::Client.new(api_key: "XXX")
+#or
+client = ChatWork::Client.new(access_token: "XXX")
+```
+
+Then call instance methods.
+
+e.g. post message.
+
+```ruby
+client.create_message(room_id: 1234, body: "Hello, ChatWork!")
+#=> #<Hashie::Mash message_id="1234567890">
+```
+
+All available APIs are followings.
+
+http://www.rubydoc.info/gems/chatwork/ChatWork/Client
 
-``` sh
-$ cat refresh_access_token.rb
-require "chatwork"
+When you want to refresh access token, call [`ChatWork::OAuthClient#refresh_access_token`](lib/chatwork/oauth_client/token_methods.rb).
 
-token = ChatWork::Token.refresh_access_token(ENV["REFRESH_TOKEN"])
+```ruby
+refresh_token = "XXX"
+oauth_client = ChatWork::OAuthClient.new(client_id: "xxx", client_secret: "xxx")
+token = oauth_client.refresh_access_token(refresh_token)
 new_access_token = token["access_token"]
 
 # Create message
-ChatWork.access_token = new_access_token
-ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
-$ CHATWORK_CLIENT_ID=xxx CHATWORK_CLIENT_SECRET=xxx REFRESH_TOKEN=xxx ruby refresh_access_token.rb
+client = ChatWork::Client.new(access_token: new_access_token)
+client.create_message(room_id: 1234, body: "Hello, ChatWork!")
+```
+
+### Pros/Cons
+Class method APIs are simple, but **not threadsafe**. Instance method APIs are **threadsafe**.
+
+If you are using multiple `api_key` or `access_token` in an app and using multithreaded server (e.g. [puma](https://github.com/puma/puma)), we recommend instance method APIs.
+
+## Tips
+### Hashie::Mash
+All API methods returns `Hashie::Mash` instance.
+
+https://github.com/intridea/hashie#mash
+
+`Hashie::Mash` is very useful!
+
+```ruby
+body = ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
+#=> #<Hashie::Mash message_id="1234567890">
+
+body["message_id"]
+#=> "1234567890"
+
+body[:message_id]
+#=> "1234567890"
+
+body.message_id
+#=> "1234567890"
+```
+
+### Block arguments
+All API methods supports block argument.
+
+If block was given, return response body and response header through block arguments.
+
+```ruby
+ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!") do |body, header|
+  body
+  #=> #<Hashie::Mash message_id="1234567890">
+
+  header["X-RateLimit-Limit"]
+  #=> "100"
+  header["X-RateLimit-Remaining"]
+  #=> "0"
+  header["X-RateLimit-Reset"]
+  #=> "1390941626"
+end
+```
+
+```ruby
+client.create_message(room_id: 1234, body: "Hello, ChatWork!") do |body, header|
+  body
+  #=> #<Hashie::Mash message_id="1234567890">
+
+  header["X-RateLimit-Limit"]
+  #=> "100"
+  header["X-RateLimit-Remaining"]
+  #=> "0"
+  header["X-RateLimit-Reset"]
+  #=> "1390941626"
+end
 ```
 
 ## Reference

data/lib/chatwork.rb

@@ -9,7 +9,7 @@ module ChatWork
   autoload :ChatWorkError,      "chatwork/chatwork_error"
   autoload :Client,             "chatwork/client"
   autoload :Contacts,           "chatwork/contacts"
-  autoload :EntityMethods,      "chatwork/entity_methods"
+  autoload :Converter,          "chatwork/converter"
   autoload :File,               "chatwork/file"
   autoload :IncomingRequest,    "chatwork/incoming_request"
   autoload :InvitationLink,     "chatwork/invitation_link"
@@ -32,64 +32,96 @@ module ChatWork
   @client_secret = nil
 
   class << self
+    # @!attribute [r] api_base
+    #  @return [String]
     attr_reader :api_base
 
+    # @!attribute [r] oauth_api_base
+    #  @return [String]
     attr_reader :oauth_api_base
 
+    # @!attribute [r] api_version
+    #  @return [String]
     attr_reader :api_version
 
+    # @return [ChatWork::Client]
     def client
-      @client ||= Client.new(api_key, access_token, api_base, api_version)
+      @client ||= Client.new(api_key: api_key, access_token: access_token)
     end
 
+    # @return [ChatWork::OAuthClient]
     def oauth_client
-      @oauth_client ||= OAuthClient.new(client_id, client_secret, oauth_api_base)
+      @oauth_client ||= OAuthClient.new(client_id: client_id, client_secret: client_secret)
     end
 
+    # @param new_value [String]
     def api_base=(new_value)
       @api_base = new_value
       @client = nil
     end
 
+    # @param new_value [String]
+    def api_version=(new_value)
+      @api_version = new_value
+      @client = nil
+    end
+
+    # @param new_value [String]
     def oauth_api_base=(new_value)
       @oauth_api_base = new_value
       @oauth_client = nil
     end
 
+    # @param new_value [String]
     def api_key=(new_value)
       @api_key = new_value
       @access_token = nil
       @client = nil
     end
 
+    # @param new_value [String]
     def access_token=(new_value)
       @api_key = nil
       @access_token = new_value
       @client = nil
     end
 
+    # @param new_value [String]
     def client_id=(new_value)
       @client_id = new_value
       @oauth_client = nil
     end
 
+    # @param new_value [String]
     def client_secret=(new_value)
       @client_secret = new_value
       @oauth_client = nil
     end
 
+    # @return [String]
+    #
+    # @note if {ChatWork.api_key} is not defined, returns `ENV["CHATWORK_API_TOKEN"]`
     def api_key
       @api_key || ENV["CHATWORK_API_TOKEN"]
     end
 
+    # @return [String]
+    #
+    # @note if {ChatWork.access_token} is not defined, returns `ENV["CHATWORK_ACCESS_TOKEN"]`
     def access_token
       @access_token || ENV["CHATWORK_ACCESS_TOKEN"]
     end
 
+    # @return [String]
+    #
+    # @note if {ChatWork.client_id} is not defined, returns `ENV["CHATWORK_CLIENT_ID"]`
     def client_id
       @client_id || ENV["CHATWORK_CLIENT_ID"]
     end
 
+    # @return [String]
+    #
+    # @note if {ChatWork.client_secret} is not defined, returns `ENV["CHATWORK_CLIENT_SECRET"]`
     def client_secret
       @client_secret || ENV["CHATWORK_CLIENT_SECRET"]
     end

data/lib/chatwork/base_client.rb

@@ -3,14 +3,19 @@ require "faraday_middleware"
 
 module ChatWork
   class BaseClient
-    def initialize(api_base, api_version, header)
+    include Converter
+
+    # @param api_base [String]
+    # @param api_version [String]
+    # @param header [Hash<String,String>]
+    def initialize(api_base:, api_version: "", header:)
       default_header = {
         "User-Agent" => "ChatWork#{api_version} RubyBinding/#{ChatWork::VERSION}",
       }
 
       default_header.merge!(header)
 
-      @conn = Faraday.new("#{api_base}#{api_version}", headers: default_header) do |builder|
+      @conn = Faraday.new(api_base, headers: default_header) do |builder|
         builder.request :url_encoded
         builder.response :mashify
         builder.response :json
@@ -29,9 +34,9 @@ module ChatWork
     end
 
     Faraday::Connection::METHODS.each do |method|
-      define_method(method) do |url, *args, &block|
+      define_method(method) do |url, args = {}, &block|
         begin
-          response = @conn.__send__(method, @api_version + url, *args)
+          response = @conn.__send__(method, @api_version + url, hash_compact(args))
         rescue Faraday::Error::ClientError => e
           raise ChatWork::APIConnectionError.faraday_error(e)
         end

data/lib/chatwork/client.rb

@@ -1,13 +1,48 @@
 module ChatWork
   class Client < BaseClient
-    def initialize(api_key, access_token, api_base, api_version)
-      if api_key
-        super(api_base, api_version, { "X-ChatWorkToken" => api_key })
-      elsif access_token
-        super(api_base, api_version, { "Authorization" => "Bearer #{access_token}" })
-      else
-        raise "Either api_key or access_token is required"
-      end
+    require "chatwork/client/contacts_methods"
+    require "chatwork/client/file_methods"
+    require "chatwork/client/incoming_request_methods"
+    require "chatwork/client/invitation_link_methods"
+    require "chatwork/client/me_methods"
+    require "chatwork/client/member_methods"
+    require "chatwork/client/message_methods"
+    require "chatwork/client/my_status_methods"
+    require "chatwork/client/my_task_methods"
+    require "chatwork/client/room_methods"
+    require "chatwork/client/task_methods"
+
+    include ContactsMethods
+    include FileMethods
+    include IncomingRequestMethods
+    include InvitationLinkMethods
+    include MeMethods
+    include MemberMethods
+    include MessageMethods
+    include MyStatusMethods
+    include MyTaskMethods
+    include RoomMethods
+    include TaskMethods
+
+    # @param api_key      [String]
+    # @param access_token [String]
+    # @param api_base     [String] default is {ChatWork.api_base}
+    # @param api_version  [String] default is {ChatWork.api_version}
+    # @note Either api_key or access_token is required
+    def initialize(api_key: nil, access_token: nil, api_base: nil, api_version: nil)
+      api_base    ||= ChatWork.api_base
+      api_version ||= ChatWork.api_version
+
+      header =
+        if api_key
+          { "X-ChatWorkToken" => api_key }
+        elsif access_token
+          { "Authorization" => "Bearer #{access_token}" }
+        else
+          raise "Either api_key or access_token is required"
+        end
+
+      super(api_base: api_base, api_version: api_version, header: header)
     end
   end
 end

data/lib/chatwork/client/contacts_methods.rb

@@ -0,0 +1,29 @@
+module ChatWork::Client::ContactsMethods
+  # Get the list of your contacts
+  #
+  # @see http://developer.chatwork.com/ja/endpoint_contacts.html#GET-contacts
+  # @see http://download.chatwork.com/ChatWork_API_Documentation.pdf
+  #
+  # @yield [response_body, response_header] if block was given, return response body and response header through block arguments
+  # @yieldparam response_body [Array<Hashie::Mash>] response body
+  # @yieldparam response_header [Hash<String, String>] response header (e.g. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
+  #
+  # @return [Array<Hashie::Mash>]
+  #
+  # @example response format
+  #   [
+  #     {
+  #       "account_id": 123,
+  #       "room_id": 322,
+  #       "name": "John Smith",
+  #       "chatwork_id": "tarochatworkid",
+  #       "organization_id": 101,
+  #       "organization_name": "Hello Company",
+  #       "department": "Marketing",
+  #       "avatar_image_url": "https://example.com/abc.png"
+  #     }
+  #   ]
+  def get_contacts(&block)
+    get("/contacts", &block)
+  end
+end

data/lib/chatwork/client/file_methods.rb

@@ -0,0 +1,67 @@
+module ChatWork::Client::FileMethods
+  # Get the list of files associated with the specified chat
+  #
+  # @param room_id [Integer]
+  # @param account_id [Integer]
+  #
+  # @see http://developer.chatwork.com/ja/endpoint_rooms.html#GET-rooms-room_id-files
+  # @see http://download.chatwork.com/ChatWork_API_Documentation.pdf
+  #
+  # @yield [response_body, response_header] if block was given, return response body and response header through block arguments
+  # @yieldparam response_body [Array<Hashie::Mash>] response body
+  # @yieldparam response_header [Hash<String, String>] response header (e.g. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
+  #
+  # @return [Array<Hashie::Mash>]
+  #
+  # @example response format
+  #   [
+  #     {
+  #       "file_id": 3,
+  #       "account": {
+  #         "account_id": 123,
+  #         "name": "Bob",
+  #         "avatar_image_url": "https://example.com/ico_avatar.png"
+  #       },
+  #       "message_id": "22",
+  #       "filename": "README.md",
+  #       "filesize": 2232,
+  #       "upload_time": 1384414750
+  #     }
+  #   ]
+  def get_files(room_id:, account_id:, &block)
+    get("/rooms/#{room_id}/files", account_id: account_id, &block)
+  end
+
+  # Get information about the specified file
+  #
+  # @see http://developer.chatwork.com/ja/endpoint_rooms.html#GET-rooms-room_id-files-file_id
+  # @see http://download.chatwork.com/ChatWork_API_Documentation.pdf
+  #
+  # @param room_id [Integer]
+  # @param file_id [Integer]
+  # @param create_download_url [Boolean] whether or not to create a download link.
+  #                                      If set to true, download like will be created for 30 seconds
+  #
+  # @yield [response_body, response_header] if block was given, return response body and response header through block arguments
+  # @yieldparam response_body [Hashie::Mash] response body
+  # @yieldparam response_header [Hash<String, String>] response header (e.g. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
+  #
+  # @return [Hashie::Mash]
+  #
+  # @example response format
+  #   {
+  #     "file_id":3,
+  #     "account": {
+  #       "account_id":123,
+  #       "name":"Bob",
+  #       "avatar_image_url": "https://example.com/ico_avatar.png"
+  #     },
+  #     "message_id": "22",
+  #     "filename": "README.md",
+  #     "filesize": 2232,
+  #     "upload_time": 1384414750
+  #   }
+  def find_file(room_id:, file_id:, create_download_url: nil, &block)
+    get("/rooms/#{room_id}/files/#{file_id}", create_download_url: boolean_to_integer(create_download_url), &block)
+  end
+end