mushikago-sdk 0.1.3 → 0.1.4

data/lib/mushikago/auth/signature.rb

@@ -1,6 +1,13 @@
 module Mushikago
   module Auth
+    # MushikagoのリクエストにMix-inして利用する
     module Signature
+      # リクエストの情報から以下のような署名用文字列を作成する
+      #   GET
+      #   localhost
+      #   /1/info.json
+      #   api_key=api_key&timestamp=2011-09-01T00%3A00%3A00Z
+      # @return [String] 署名用の文字列
       def string_to_sign
         [
           http_method,
@@ -10,6 +17,8 @@ module Mushikago
         ].join("\n")
       end
 
+      # リクエストに署名を追加する
+      # @param signer [Mushikago::Auth::Signer] 署名を作成するオブジェクト
       def add_signature! signer
         set_param('signature', signer.sign(string_to_sign))
       end

data/lib/mushikago/auth/signer.rb

@@ -3,12 +3,19 @@ require 'openssl'
 
 module Mushikago
   module Auth
+    # 署名を作成するクラス
     class Signer
+      # @return [String] シークレットキー
       attr_reader :secret_key
+
+      # @param [String] secret_key シークレットキー
       def initialize secret_key
         @secret_key = secret_key
       end
 
+      # @param [String] string_to_sign 署名の元になる文字列
+      # @param [String] digest_method 署名作成のアルゴリズム
+      # @return [String] 署名
       def sign(string_to_sign, digest_method='sha256')
         Base64.encode64(
           OpenSSL::HMAC.digest(

data/lib/mushikago/auth.rb

@@ -1,4 +1,5 @@
 module Mushikago
+  # Mushikagoサービスの認証を扱うモジュール
   module Auth
     autoload :Signature, 'mushikago/auth/signature'
     autoload :Signer, 'mushikago/auth/signer'

data/lib/mushikago/configuration.rb

@@ -4,11 +4,11 @@ module Mushikago
     include Singleton
 
     # @param [Hash] options optionsをロードします
-    # @option options [string] :api_key('環境変数：MUSHIKAGO_API_KEY') 発行されたAPIKeyを設定する
-    # @option options [string] :secret_key('環境変数：MUSHIKAGO_SECRET_KEY') 発行されたSecretKeyを設定する
-    # @option options [string] :tombo_endpoint('tombo.mushikago.org') tomboサービスのエンドポイントを設定する
+    # @option options [String] :api_key(ENV['MUSHIKAGO_API_KEY']) 発行されたAPIKeyを設定する
+    # @option options [String] :secret_key(ENV['MUSHIKAGO_SECRET_KEY']) 発行されたSecretKeyを設定する
+    # @option options [String] :tombo_endpoint('tombo.mushikago.org') tomboサービスのエンドポイントを設定する
     # @example
-    #   Mushikago::Config.load(:api_key => 'ABCDEFG', :secret_key => 'HIJKLMN')
+    #   Mushikago.config.load(:api_key => 'ABCDEFG', :secret_key => 'HIJKLMN')
     def load options={}
       options.each do |key, value|
         supplied[key.to_sym] = value
@@ -20,6 +20,8 @@ module Mushikago
       # @param [Object] default_value デフォルト値
       # @param [Hash] options 型情報を補足的に追加することができる
       # @param [Block] transform 渡された値を変換するブロック
+      # @option options [Symbol] :boolean 自動的にname?のエイリアスメソッドが生成されます
+      private
       def add_option name, default_value = nil, options = {}, &transform
         name = name.to_sym
         raise "The option #{name} is already defined!" if self.respond_to?(name)
@@ -31,10 +33,6 @@ module Mushikago
 
         alias_class_method("#{name}?", name) if options[:boolean]
       end
-      
-      def load options={}
-        instance.load options
-      end
     end
     
     add_option :api_key, ENV['MUSHIKAGO_API_KEY'] || ENV['MUSHIKAGO_API_KEY_ID']

data/lib/mushikago/http/client.rb

@@ -0,0 +1,37 @@
+require 'net/http'
+require 'json'
+module Mushikago
+  module Http
+    class Client
+      # @return [String] api_key
+      attr_reader :api_key
+
+      # @return [Signer] signer
+      attr_reader :signer
+
+      # @param [Hash] options
+      # @option options [String] :api_key(Configured value) APIキー
+      # @option options [String] :secret_key(Configured value) 秘密鍵
+      def initialize options={}
+        @api_key = (options[:api_key] || Mushikago.config.api_key).to_s
+        @signer = Mushikago::Auth::Signer.new((options[:secret_key] || Mushikago.config.secret_key).to_s)
+      end
+
+      # @param [Mushikago::Http::Request] request
+      # @return [Mushikago::Http::Response] response
+      def send_request request
+        # add authorization
+        request.set_param('api_key', api_key)
+        request.set_param('timestamp', Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ'))
+        request.add_signature!(signer)
+
+        # send request
+        Net::HTTP.start(request.host, request.port) do |http|
+          http_request = request.to_http_request
+          http_response = http.request(http_request)
+          return Mushikago::Http::Response.new(JSON.parse(http_response.body)) 
+        end
+      end
+    end
+  end
+end

data/lib/mushikago/http/response.rb

@@ -1,14 +1,46 @@
 module Mushikago
   module Http
+    # Mushikagoサービスのレスポンスを扱うクラス
+    # Mushikagoサービスのレスポンスは以下のような構造になっている
+    #   {
+    #     meta : {
+    #       status : 200,
+    #       message : 'OK'
+    #     },
+    #     response : {
+    #       // サービス毎に異なる情報
+    #     }
+    #   }
+    #
     class Response
+      # @return [Object] レスポンスのメタ情報
       attr_reader :meta
+      # @return [Object] レスポンスの本体
       attr_reader :response
       
+      # @param [Hash] options オプション
+      # @option options [Object] :meta レスポンスのメタ情報
+      # @option options [Object] :response レスポンスの本体
       def initialize options={}
         @meta = options[:meta] || options['meta']
         @response = options[:response] || options['response']
       end
 
+      # メタ情報中のstatusを返す
+      # @return [Integer] ステータス
+      def status
+        meta[:status].to_i
+      end
+
+      # メタ情報中のmessageを返す
+      # @return [String] メッセージ
+      def message
+        meta[:message]
+      end
+
+      # レスポンスの各要素にアクセスする
+      # @param [Symbol] key レスポンスの各要素へのキー
+      # @return [Object] レスポンスの要素
       def [] key
         response[key]
       end

data/lib/mushikago/http.rb

@@ -1,5 +1,7 @@
 module Mushikago
+  # MushikagoサービスへのHTTPリクエストを扱うモジュール
   module Http
+    autoload :Client, 'mushikago/http/client'
     autoload :Request, 'mushikago/http/request'
     autoload :Response, 'mushikago/http/response'
   end

data/lib/mushikago/tombo/capture_request.rb

@@ -3,10 +3,16 @@ module Mushikago
     class CaptureRequest < Request
       add_param :url
       add_param :image_format
-      add_param :image_quality
+      add_param :image_quality do |v| v.to_i.to_s end
       add_param :thumbnail do |v| (v.to_i != 0 ? 1 : 0).to_s end
       add_param :tags do |v| [v].flatten.compact.join(',') end
 
+      # @param [String] url キャプチャ対象のURL
+      # @param [Hash] options リクエストのオプション
+      # @option options [String] :image_format('jpg') 画像のフォーマット(jpg,png)
+      # @option options [Integer] :image_quality(80) 画像の品質(0-100)
+      # @option options [Boolean] :thumbnail(0) サムネイル取得フラグ(false:取得しない,true:取得する)
+      # @option options [String,Array] :tags タグ
       def initialize url, options={}
         super(options)
         self.url = url

data/lib/mushikago/tombo/captures_request.rb

@@ -7,6 +7,12 @@ module Mushikago
       add_param :domain
       add_param :tag
 
+      # @param [Hash] options リクエストのオプション
+      # @option options [String] :id 画像のID
+      # @option options [String] :domain 指定したドメインの画像一覧を取得する
+      # @option options [String] :tag 指定したタグの画像一覧を取得する
+      # @option options [Integer] :limit(10) 最大取得件数(1-100)
+      # @option options [Integer] :offset(0) 取得オフセット
       def initialize options={}
         super(options)
         self.id = options[:id] if options.has_key?(:id)

data/lib/mushikago/tombo/client.rb

@@ -1,21 +1,71 @@
 module Mushikago
   module Tombo
-    class Client < Mushikago::Client
+    # Tomboサービスを利用する
+    #
+    # @example
+    #   client = Mushikago::Tombo::Client.new(:api_key => '<api_key>', :secret_key => '<secret_key>')
+    #
+    #   client.capture('http://www.tombo.ne.jp/', :thumbnail => true, :tags => ['tombo', 'webservice'])
+    #
+    #   captures = client.captures
+    #   captures['images'].each do |image|
+    #     puts image['image_url']
+    #   end
+    #
+    # @example APIキーをファイルから読み込む場合
+    #   Mushikago.config.load(YAML.load(File.read(mushikago.yml)))
+    #   client = Mushikago::Tombo::Client.new
+    class Client < Mushikago::Http::Client
+      # 指定したURLのキャプチャを取得する
+      #
+      # @param [String] url キャプチャ対象のURL
+      # @param [Hash] options リクエストのオプション
+      # @option options [String] :image_format('jpg') 画像のフォーマット(jpg,png)
+      # @option options [Integer] :image_quality(80) 画像の品質(0-100)
+      # @option options [Boolean] :thumbnail(0) サムネイル取得フラグ(false:取得しない,true:取得する)
+      # @option options [String,Array] :tags タグ
+      # @example
+      #   client.capture('http://www.tombo.ne.jp/', :thumbnail => true, :tags => ['tombo', 'webservice'])
+      # @return [Mushikago::Http::Response] リクエストの結果
       def capture url, options={}
         request = CaptureRequest.new(url, options)
         send_request(request)
       end
 
+      # いままでキャプチャした画像の情報を取得する
+      #
+      # @param [Hash] options リクエストのオプション
+      # @option options [String] :id 画像のID
+      # @option options [String] :domain 指定したドメインの画像一覧を取得する
+      # @option options [String] :tag 指定したタグの画像一覧を取得する
+      # @option options [Integer] :limit(10) 最大取得件数(1-100)
+      # @option options [Integer] :offset(0) 取得オフセット
+      # @example
+      #   client.captures(:tag => 'webservice')
+      # @return [Mushikago::Http::Response] リクエストの結果
       def captures options={}
         request = CapturesRequest.new(options)
         send_request(request)
       end
 
+      # 指定した画像を削除する
+      #
+      # @param [String] id 画像のID
+      # @param [Hash] options リクエストのオプション
+      # @example
+      #   client.delete('5a6cdfa3-xxx3-47d6-8xxx-5f83af6b66cc')
+      # @return [Mushikago::Http::Response] リクエストの結果
       def delete id, options={}
         request = DeleteRequest.new(id, options)
         send_request(request)
       end
 
+      # APIの使用状況を取得する
+      #
+      # @param [Hash] options リクエストのオプション
+      # @example
+      #   client.info
+      # @return [Mushikago::Http::Response] リクエストの結果
       def info options={}
         request = InfoRequest.new(options)
         send_request(request)

data/lib/mushikago/tombo/delete_request.rb

@@ -3,6 +3,8 @@ module Mushikago
     class DeleteRequest < Request
       add_param :id
 
+      # @param [String] id 画像のID
+      # @param [Hash] options リクエストのオプション
       def initialize id, options={}
         super(options)
         self.id = id

data/lib/mushikago/tombo/info_request.rb

@@ -1,6 +1,7 @@
 module Mushikago
   module Tombo
     class InfoRequest < Request
+      # @param [Hash] options リクエストのオプション 
       def initialize options={}
         super(options)
         @path = "/#{api_version}/info.json"

data/lib/mushikago/tombo.rb

@@ -1,4 +1,5 @@
 module Mushikago
+  # Tomboへのアクセスを行うモジュール
   module Tombo
     autoload :Client, 'mushikago/tombo/client'
     autoload :Request, 'mushikago/tombo/request'

data/lib/mushikago/version.rb

@@ -1,3 +1,3 @@
 module Mushikago
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

data/lib/mushikago.rb

@@ -1,13 +1,14 @@
+# Mushikagoサービスを提供するモジュール
 module Mushikago
   # class
   autoload :Config, 'mushikago/configuration'
-  autoload :Client, 'mushikago/client'
 
   # module
   autoload :Http, 'mushikago/http'
   autoload :Auth, 'mushikago/auth'
   autoload :Tombo, 'mushikago/tombo'
 
+  # @return [Mushikago::Config] config コンフィグのインスタンスへのアクセスを提供する
   def self.config
     Config.instance
   end

data/spec/mushikago/configuration_spec.rb

@@ -32,7 +32,7 @@ describe Mushikago::Config do
   # Mushikago::Configは値をロードすることができる
   context 'loads option value' do
     before :all do
-      Mushikago::Config.load(
+      Mushikago::Config.instance.load(
         :api_key => 'api_key',
         :secret_key => 'secret_key',
         :tombo_endpoint => 'tombo.mushikago.org'
@@ -47,7 +47,7 @@ describe Mushikago::Config do
     # ロードする際のキーは文字列でもOK
     context 'loading options key can be string' do
       before :all do
-        Mushikago::Config.load(
+        Mushikago::Config.instance.load(
           'api_key' => 'api_key',
           'secret_key' => 'secret_key',
           'tombo_endpoint' => 'tombo.mushikago.org'

data/spec/mushikago/{client_spec.rb → http/client_spec.rb}

@@ -5,10 +5,10 @@ class TestRequest < Mushikago::Http::Request
 end
 
 
-describe Mushikago::Client do
+describe Mushikago::Http::Client do
   context 'construct without options' do
     before :all do
-      @client = Mushikago::Client.new
+      @client = Mushikago::Http::Client.new
     end
 
     subject{ @client }
@@ -18,7 +18,7 @@ describe Mushikago::Client do
 
   context 'construct with options' do
     before :all do
-      @client = Mushikago::Client.new(
+      @client = Mushikago::Http::Client.new(
         :api_key => 'mushikago api key'
       )
     end
@@ -33,7 +33,7 @@ describe Mushikago::Client do
       request = TestRequest.new
       request.host = 'tombo.mushikago.org'
       request.path = '/1/info.json'
-      client = Mushikago::Client.new
+      client = Mushikago::Http::Client.new
       @response = client.send_request(request)
     end
     subject{ @response }

data/spec/mushikago/http/response_spec.rb

@@ -17,10 +17,13 @@ describe Mushikago::Http::Response do
   subject{ @response }
 
   it{ should respond_to(:meta, :response) }
+  it{ should respond_to(:status, :message) }
   it{ should respond_to(:[]) }
 
   it{ subject.meta[:status].should == 200 }
+  it{ subject.status.should == 200 }
   it{ subject.meta[:message].should == 'OK' }
+  it{ subject.message.should == 'OK' }
   it{ subject.response[:hello].should == 'world' }
   it{ subject[:hello].should == 'world' }
 end

data/spec/mushikago/tombo/capture_request_spec.rb

@@ -35,6 +35,7 @@ describe Mushikago::Tombo::CaptureRequest do
     it{ subject.image_quality.should == '20' }
     it{ subject.thumbnail.should == '1' }
     it{ subject.tags.should == 'hoge,fuga' }
+    it{ subject.headers['Content-type'].should == 'application/x-www-form-urlencoded; charset=utf-8' }
     it{ subject.url_encoded_params.should == 'image_format=png&image_quality=20&tags=hoge%2Cfuga&thumbnail=1&url=http%3A%2F%2Fwww.mushikago.org%2F' }
   end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mushikago-sdk
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 19
   prerelease: 
   segments: 
   - 0
   - 1
-  - 3
-  version: 0.1.3
+  - 4
+  version: 0.1.4
 platform: ruby
 authors: 
 - Toru Matsuoka
@@ -142,11 +142,10 @@ files:
 - lib/mushikago/configuration.rb
 - lib/mushikago/http/request.rb
 - lib/mushikago/http/response.rb
-- lib/mushikago/client.rb
+- lib/mushikago/http/client.rb
 - lib/mushikago/http.rb
 - lib/mushikago-sdk.rb
 - spec/spec_helper.rb
-- spec/mushikago/client_spec.rb
 - spec/mushikago/auth/signer_spec.rb
 - spec/mushikago/auth/signature_spec.rb
 - spec/mushikago/tombo/client_spec.rb
@@ -156,6 +155,7 @@ files:
 - spec/mushikago/tombo/info_request_spec.rb
 - spec/mushikago/tombo/capture_request_spec.rb
 - spec/mushikago/configuration_spec.rb
+- spec/mushikago/http/client_spec.rb
 - spec/mushikago/http/response_spec.rb
 - spec/mushikago/http/request_spec.rb
 homepage: http://www.mushikago.org/
@@ -193,7 +193,6 @@ specification_version: 3
 summary: A SDK for Mushikago.
 test_files: 
 - spec/spec_helper.rb
-- spec/mushikago/client_spec.rb
 - spec/mushikago/auth/signer_spec.rb
 - spec/mushikago/auth/signature_spec.rb
 - spec/mushikago/tombo/client_spec.rb
@@ -203,5 +202,6 @@ test_files:
 - spec/mushikago/tombo/info_request_spec.rb
 - spec/mushikago/tombo/capture_request_spec.rb
 - spec/mushikago/configuration_spec.rb
+- spec/mushikago/http/client_spec.rb
 - spec/mushikago/http/response_spec.rb
 - spec/mushikago/http/request_spec.rb

data/lib/mushikago/client.rb

@@ -1,35 +0,0 @@
-require 'net/http'
-require 'json'
-module Mushikago
-  class Client
-    # @return [String] api_key
-    attr_reader :api_key
-
-    # @return [Signer] signer
-    attr_reader :signer
-
-    # @param [Hash] options
-    # @option options [String] :api_key(Configured value) APIキー
-    # @option options [String] :secret_key(Configured value) 秘密鍵
-    def initialize options={}
-      @api_key = (options[:api_key] || Mushikago.config.api_key).to_s
-      @signer = Mushikago::Auth::Signer.new((options[:secret_key] || Mushikago.config.secret_key).to_s)
-    end
-
-    # @param [Mushikago::Http::Request] request
-    # @return [Mushikago::Http::Response] response
-    def send_request request
-      # add authorization
-      request.set_param('api_key', api_key)
-      request.set_param('timestamp', Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ'))
-      request.add_signature!(signer)
-
-      # send request
-      Net::HTTP.start(request.host, request.port) do |http|
-        http_request = request.to_http_request
-        http_response = http.request(http_request)
-        return Mushikago::Http::Response.new(JSON.parse(http_response.body)) 
-      end
-    end
-  end
-end