easy_ping 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7cd4ae3fc608c08d9dcf7c6c485f93927f2225d6
+  data.tar.gz: 0fb57d8dfcf98107bd7493862e0b4327acb6ec31
+SHA512:
+  metadata.gz: 66012954677b41c3a2bd85bbcf4c35835ec05f1767f1fa1713d0201bac9ef50fd80238be5d4f85199659a72582f3d7884b2e676e4dc9212b70e8cf5f497e1f24
+  data.tar.gz: 5741090b288a91c5c145e8d0d1eabc7b7d176037ee7b465f00c01bf98cbed0658e33a82cd4d9239a00da955b30cd83252299a11f518463b2ad4976cb02188214

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in easy_ping.gemspec
+gemspec
+

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Xiaoguang Chen
+
+MIT License
+
+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,299 @@
+# EasyPing
+
+EasyPing is an out of the box Ping++ Ruby SDK. Once installed, you're ready to set up a minimal configuration and get started using EasyPing.
+
+**Warn UNDER DEVELOPMENT** Not ready for production purpose yet.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'easy_ping'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install easy_ping
+
+If you prefer to use the latest code, you can build from source:
+
+```
+gem build easy_ping.gemspec
+gem install easy_ping-<VERSION>.gem
+```
+
+## Configuration
+
+Write these lines of code to your configuration file, for example, `easy_ping.rb`.
+
+```ruby
+EasyPing.configure do |config|
+  config.app_id   = 'app_Wzrrb9DW1GaLmbjn' # required
+  config.api_key = 'sk_test_Dq54mDyHufz9nrPeH8Hm50G8' # required
+  config.channel = :alipay # optional, default: :alipay, you can modify this option on runtime
+end
+```
+
+And put it under `config/initiailizers` directory of your Rails project.
+
+Or require this file manually by yourself.
+
+## Usage
+
+```ruby
+## Create Charge ##
+
+# Class Method Definitions : Charge Create
+EasyPing::Charge.create(order_number, amount, subject, body, options={}) -> charge object
+EasyPing::Charge.create(options) -> charge object
+
+# Alias Methods
+EasyPing::Charge.create
+EasyPing.charge
+
+# Examples
+charge = EasyPing::Charge.create 'order_number_1', 100, 'apple', 'one delicous big apple'
+charge = EasyPing.charge({
+  order_number: 'order_number_2',
+  amount:       100,
+  subject:      'apple',
+  body:         'one delicous big apple',
+  app_id:       'app_Wzrrb9DW1GaLmbjn',
+  metadata:     { color: 'red'},
+})
+
+
+## Retrieve Single Charge ##
+
+# Class Method Definitions : Charge Find
+EasyPing::Charge.find(charge_id) -> charge object
+EasyPing::Charge.find(charge_id: charge_id) -> charge object
+
+# Alias Methods
+EasyPing::Charge.find
+EasyPing.find
+EasyPing.find_charge
+
+# Examples
+charge = EasyPing::Charge.find 'ch_8OG4WDTe10q1q5G8aL8aDSmH'
+charge = EasyPing.find charge_id: 'ch_8OG4WDTe10q1q5G8aL8aDSmH'
+
+
+## Retrieve Charge List ##
+
+# Class Method Definitions : Charge ALL
+EasyPing::Charge.all(options={}) -> charge object list
+
+# Alias Methods
+EasyPing::Charge.all
+EasyPing.all
+EasyPing.all_charges
+EasyPing.get_charge_list
+
+# Examples
+charges = EasyPing::Charge.all
+charges = EasyPing.all {
+  limit:      10,
+  offset:     'ch_8OG4WDTe10q1q5G8aL8aDSmH', # offset & starting_after, synonym
+  paid:       true,
+  refunded:   false
+}
+
+# Instance Method Definitions : Charge Pagination
+charges.get_next_page(options={}) -> charge object list
+
+# Similar Methods
+charges.get_next_page
+charges.get_next_page! # change charges itself
+charges.get_prev_page
+charges.get_prev_page! # same above
+
+# Examples
+new_charges = charges.get_next_page # note: ending_before option will be omitted
+charges.get_prev_page!(limit: 5) # note: starting_after option will be omitted
+
+
+## Create Refund ##
+
+# Class Method Definitions : Refund Create
+EasyPing::Refund.create(description, charge_id) -> refund object
+EasyPing::Refund.create(amount, description, charge_id) -> refund object
+EasyPing::Refund.create(options) -> refund object
+
+# Alias Methods
+EasyPing::Refund.create
+EasyPing.refund
+
+# Examples
+EasyPing::Refund.create 'refund description', 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
+EasyPing.refund({
+  amount:      50,
+  description: 'refund description',
+  charge_id:   'ch_0ijQi5LKqT5sEiOePOKWb1mF'
+})
+
+# Instance Method Definitions : Refund Create
+charge.refund(amount description) -> refund object
+charge.refund(description) -> refund object
+charge.refund(options) -> refund object
+
+# Examples
+charge = EasyPing::Charge.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
+refund = charge.refund 10, 'refund description'
+
+
+## Retrieve Single Refund ##
+
+# Class Method Definitions : Refund Find
+EasyPing::Refund.find(charge_id, refund_id) -> refund object
+EasyPing::Refund.find(options) -> refund object
+
+# Alias Methods
+EasyPing::Refund.find
+EasyPing.find
+EasyPing.find_refund
+
+# Special Note:
+#   Must provide both charge_id and refund_id,
+#   if only charge_id provided, it will retrieve a charge object
+
+# Examples
+refund = EasyPing::Refund.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF', 're_TmbvDKHiXLCSG0mnj9jnDyjA'
+refund = EasyPing.find_refund charge_id: 'ch_0ijQi5LKqT5sEiOePOKWb1mF', refund_id: 're_TmbvDKHiXLCSG0mnj9jnDyjA'
+
+
+## Retrieve Refund List ##
+
+# Class Method Definitions : Refund All
+EasyPing::Refund.all(charge_id, options={}) -> refund object list
+EasyPing::Refund.all(options) -> refund object list
+
+# Alias Methods
+EasyPing::Refund.all
+EasyPing.all_refund
+EasyPing.all_refunds # in case of plural format typo
+EasyPing.get_refund_list
+
+# Examples
+refund_list = EasyPing::Refund.all 'ch_0ijQi5LKqT5sEiOePOKWb1mF', { limit: 5 }
+refund_list = EasyPing.all_refund charge_id: 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
+
+# Instance Method Definitions : Refund All
+charge.all_refund(options={}) -> refund object list
+
+# Alias Methods
+charge.all_refund
+charge.all_refunds # in case of typo
+charge.get_refund_list
+
+# Examples
+charge = EasyPing::Charge.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
+refund_list = charge.all_refund limit: 5
+```
+
+Retrieve charge or refund object from async notification is easy.
+EasyPing will automatically detect whether response object is charge
+or refund.
+
+```ruby
+## Retrieve from Async Notification ##
+
+# Class Method Definitions : Async Notification
+EasyPing.from_notification(params) -> charge/refund object
+
+# Alias Methods
+EasyPing::Charge.from_notification(params)
+EasyPing::Refund.from_notification(params)
+
+# Special Note:
+#   1. params can a JSON string or a decoded hash object
+#   2. it will automatically detect charge/refund object
+#      no matter which method you call
+
+# Examples
+charge = EasyPing::Charge.from_notification(params)
+refund = EasyPing::Refund.from_notification(params)
+```
+
+## Advanced Usage
+
+```ruby
+## Runtime Setup ##
+
+# Using different configuration from pre-setup options
+ping = EasyPing.new({
+  app_id:   'app_Wzrrb9DW1GaLmbjn',
+  api_key: 'sk_test_Dq54mDyHufz9nrPeH8Hm50G8',
+  channel:  :wx
+})
+
+# do whatever you want without change of default configuration
+ping.charge 'order_number_3' 100, 'apple', 'one delicous big apple'
+
+## Helpers ##
+
+# instance helpers
+charge.raw # raw response body, typically json string
+charge.values # response body, hash
+charge.heasers # response headers
+charge.status # response status, http code
+charge.live? # livemode or not
+
+# all attributes
+charge.amount
+charge.livemode
+charge.refunded
+
+# note: refund objects apply same rules above
+
+## Config ##
+config = EasyPing.config
+
+config.api_key
+config.app_id
+config.to_options # return config in hash format
+
+EasyPing.config # return default config
+
+ping = EasyPing.new({
+  app_id:   'app_Wzrrb9DW1GaLmbjn',
+  api_key: 'sk_test_Dq54mDyHufz9nrPeH8Hm50G8',
+})
+ping.config # return config for this ping instance
+
+## Available Channels ##
+["alipay", "wx", "upmp", "alipay_wap", "upmp_wap"]
+```
+
+## Error Handling
+
+If fail to create or retrieve charge/refund, an error will be raised.
+
+```ruby
+## Error ##
+
+begin
+  charge = EasyPing::Charge.find 'ch_0ijQi5LKqT5sEiOePOKWb1mF'
+rescue EasyPing::APIError => e # Error return by server
+  puts e.message
+  puts e.status
+  puts e.type
+  puts e.param
+rescue EasyPing::Error => e # Top level error of EasyPing
+  puts e.message
+rescue Exception => boom
+  puts "something wrong with your code, #{boom.message}"
+  puts boom.backtrace.join("\n")
+end
+```
+
+## Others
+
+For Ping++ API information, please visit https://pingplusplus.com/document/api
+
+If something doesn't work, feel free to report a bug or start an issue.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/easy_ping.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'easy_ping/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "easy_ping"
+  spec.version       = EasyPing::VERSION
+  spec.authors       = ["Cxg"]
+  spec.email         = ["xg.chen87@gmail.com"]
+  spec.summary       = "Ruby Wrapper for Ping++ API}"
+  spec.description   = %q{EasyPing is an out of the box Ping++ Ruby SDK.
+                          For Ping++ API information, please
+                          visit https://pingplusplus.com for details.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0") - %w[.gitignore]
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'faraday', '~> 0.9.0'
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/easy_ping.rb

@@ -0,0 +1,29 @@
+require 'json'
+require 'faraday'
+
+require 'easy_ping/version'
+require 'easy_ping/error'
+require 'easy_ping/utils'
+require 'easy_ping/config'
+require 'easy_ping/model'
+require 'easy_ping/action'
+require 'easy_ping/base'
+
+module EasyPing
+
+  class << self
+    def new(options)
+      EasyPing::Base.new(options)
+    end
+
+  private
+    def method_missing(name, *args, &block)
+      default_proxy.send name, *args, &block
+    end
+  end
+
+  def self.default_proxy
+    @default_proxy ||= EasyPing::Base.new
+  end
+
+end

data/lib/easy_ping/action.rb

@@ -0,0 +1,200 @@
+require 'json'
+module EasyPing
+  class Client
+    def initialize(api_base, api_key)
+      options = {ssl: {ca_file: '../ssl/ca-certificates.crt'}}
+      @connection = Faraday.new(api_base, options) do |conn|
+        conn.request       :url_encoded
+        conn.response      :logger
+        conn.authorization :Bearer, api_key
+        conn.adapter       Faraday.default_adapter
+      end
+
+      def run(method, *args)
+        @connection.send method, *args
+      rescue Faraday::ClientError => e
+        raise EasyPing::HTTPClientError.new(e)
+      end
+    end
+  end
+
+  class Action
+    include EasyPing::Utils
+    CHANNELS = ["alipay", "wx", "upmp", "alipay_wap", "upmp_wap"]
+
+    attr_reader :client, :config
+
+    def initialize(config)
+      @config = config
+      @client   = EasyPing::Client.new(config.api_base, config.api_key)
+    end
+
+    def from_notification(params)
+      EasyPing::Model::Wrapper.new(params, config)
+    end
+
+    extend Forwardable
+    # delegators to response
+    def_delegators :config, :live, :live?, :channel
+
+  private
+    def compile(options)
+      mappings.each do |*group|
+        raise ParametersInvalid, "more than one of #{group} options set" if (options.keys & group).length > 1
+      end
+      Hash[options.map {|k, v| mappings.key?(k) ? [mappings[k], v] : [k, v] }]
+    end
+
+    def verify!(options, requires)
+      missing_parameters = requires - options.keys.map(&:to_s)
+      if missing_parameters.length > 0
+        raise MissingRequiredParameters, %Q{#{missing_parameters} is required
+        for this action.}
+      end
+      if options['channel'] && !CHANNELS.include?(options['channel'].to_s)
+        raise ParametersInvalid, %Q{#{options['channel']} is not valid channel
+        for this action.}
+      end
+    end
+  end
+
+  class Refund < Action
+    def self.create(*args)
+      new(EasyPing::Base.config).refund(*args)
+    end
+
+    def initialize(config)
+      super(config)
+      @settings = config.to_options
+    end
+
+    def refund(*args)
+      amount = args.first
+      if Integer === amount
+        params = indifferent_params(args, 'amount', 'description', 'charge_id')
+      else
+        params = indifferent_params(args, 'description', 'charge_id')
+      end
+
+      # map keys to API request format and verify options
+      params = compile params
+      verify! params, refund_requires
+
+      # set up charge id for refund action
+      @charge_id = params.delete 'charge_id'
+
+      # run request and parse return result
+      raw_response = client.run(:post, api_endpoint, params)
+      EasyPing::Model::Wrapper.parse! raw_response, config
+    end
+
+    def find(*args)
+      params = indifferent_params(args, 'charge_id', 'refund_id')
+      @charge_id, @refund_id = params.values_at('charge_id', 'refund_id')
+
+      # run request and parse return result
+      raw_response = client.run :get, "#{api_endpoint}/#{@refund_id}"
+      EasyPing::Model::Wrapper.parse! raw_response, config
+    end
+
+    def all(*args)
+      params = indifferent_params(args, 'charge_id')
+
+      # map keys to API request format
+      params = compile params
+
+      # set up charge id for refund action
+      @charge_id = params.delete 'charge_id'
+
+      raw_response = client.run :get, api_endpoint, params
+      EasyPing::Model::Wrapper.parse! raw_response, config
+    end
+
+  private
+    def api_endpoint
+      "/v1/charges/#{@charge_id}/refunds"
+    end
+
+    def refund_requires
+      ['charge_id', 'description']
+    end
+
+    def mappings
+      {
+        'from'   => 'charge_id',
+        'offset' => 'starting_after'
+      }
+    end
+  end
+
+  class Charge < Action
+    REQUIRED = [
+      'order_no', 'app[id]', 'channel', 'amount', 'client_ip', 'currency',
+      'subject', 'body'
+    ]
+
+    def self.create(*args)
+      new(EasyPing::Base.config).charge(*args)
+    end
+
+    def initialize(config)
+       super(config)
+      @settings = config.to_options.merge default_charge_options
+    end
+
+    def charge(*args)
+      params = indifferent_params(args, 'order_number', 'amount', 'subject', 'body')
+      params = @settings.merge params
+
+      # map keys to API request format and verify params
+      params = compile params
+      verify! params, charge_requires
+
+      # run request and parse return result
+      raw_response = client.run(:post, api_endpoint, params)
+      EasyPing::Model::Wrapper.parse! raw_response, config
+    end
+
+    def find(*args)
+      params = indifferent_params(args, 'charge_id')
+
+      raw_response = client.run :get, "#{api_endpoint}/#{params['charge_id']}"
+      EasyPing::Model::Wrapper.parse! raw_response, config
+    end
+
+    def all(params={})
+      params = indifferent_hash params
+
+      # map keys to API request format
+      params = compile params
+
+      raw_response = client.run :get, api_endpoint, params
+      EasyPing::Model::Wrapper.parse! raw_response, config
+    end
+
+  private
+    def api_endpoint
+      '/v1/charges'
+    end
+
+    def mappings
+      {
+        'order_number' => 'order_no',
+        'app_id'       => 'app[id]',
+        'app'          => 'app[id]',
+        'offset'       => 'starting_after'
+      }
+    end
+
+    def default_charge_options
+      { 'client_ip' => '127.0.0.1' }
+    end
+
+    def charge_requires
+      [
+        'order_no', 'app[id]', 'channel', 'amount', 'client_ip',
+        'currency', 'subject', 'body'
+      ]
+    end
+  end
+end