button 1.2.0 → 2.0.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    Mjg5ZThjM2ExMjhiYmFiNjU1MTZhMzViYTIzY2NlYTNiNzc4NGM1ZQ==
-  data.tar.gz: !binary |-
-    ODBkYTM3Nzc4ZjdiODU2MDEwZWJiN2FkZTg3NTRkOTJhZTU3NGMxOQ==
+SHA1:
+  metadata.gz: c08ec518d065b7b8546110e37a06ba0b8da850ee
+  data.tar.gz: dadccf3559487db05b8618cd01e11ba71558e655
 SHA512:
-  metadata.gz: !binary |-
-    MWI4ODgzNjg0YTBkMjE5NTFiZDQ0YmI2M2MzZjJjYTg5MmE5ZGU0YWM2MjZj
-    ZjVjMjMxZGI4YTM4MmExNTM0ZDljOTg4NDRjMjIzZGIzYzlkMzJjMWE5N2U0
-    YmRiMzZiMTQ2MDZmNGQwMDI1Y2M3OTAxNTYwNWRiNTA1M2Y3ODU=
-  data.tar.gz: !binary |-
-    YmY1MGY3NjE4OTliYTU3Y2FjMTUwNjMwODkzMjYzZDNhNjg5YWI2MmU2OWUz
-    N2IzMjE1Yzg2OTVkZjM4YmU0NjMxNmMwYWMwNzI4YTE0YTAyZWEzNDk1MmU0
-    MzMxYWNhYjgxNjk1NGZiMTEyNDgwZjNkODliNTE0NTZiNDhiNDM=
+  metadata.gz: 0075f1a015a55e2524fd68c90593514bf935803f9965745342e4e4cc542cf1a269c846745392291982b9d24a6dbb06e4c9649b1e260c925aa1fe4971defbf05c
+  data.tar.gz: 953d707ea24f530da5d70bfb4dfdbab8f97240400266d37fd44706915230173df70d9da2e478484960c6843456532ddf6023c32083999c3456e9e066a42d32af

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+2.0.0 January 6, 2017
+  - Add `Accounts` resource
+  - Add `Merchants` resource
+  - Completely change `Button::Response` interface
+
 1.2.0 January 4, 2017
   - Add `Button::Utils::webhook_authentic?` function
 

data/README.md

@@ -28,7 +28,7 @@ client = Button::Client.new('sk-XXX')
 
 The client will always attempt to raise a `Button::ButtonClientError` in an error condition. 
 
-All API requests will return a `Button::Response` instance, which supports accessing data properties from the API response as methods.  To access the raw response hash, use `#to_hash`.  For instance:
+All API requests will return a `Button::Response` instance.  To access the response data, invoke `#data`.
 
 ```ruby
 require 'button'
@@ -41,17 +41,17 @@ rescue Button::ButtonClientError => error
   puts error
 end
 
-puts response 
+puts response
 # => Button::Response(button_order_id: btnorder-XXX, total: 60, ... )
 
-puts response.button_order_id
-# => btnorder-XXX
-
-puts response.to_hash()
+puts response.data
 # => {:button_order_id=>'btnorder-29de0b1436075ea6', :total=>60, ... }
+
+puts response.data[:button_order_id]
+# => btnorder-XXX
 ```
 
-n.b. the keys of the response hash will always be symbols. 
+_n.b. the keys of the response hash will always be symbols._
 
 ## Configuration
 
@@ -77,7 +77,75 @@ The supported options are as follows:
 
 ## Resources
 
-We currently expose only one resource to manage, `Orders`. 
+We currently expose the following resources to manage:
+
+* [`Accounts`](#accounts)
+* [`Merchants`](#merchants)
+* [`Orders`](#orders)
+
+### Accounts
+
+##### all
+
+```ruby
+require 'button'
+
+client = Button::Client.new('sk-XXX')
+
+response = client.accounts.all
+
+puts response
+# => Button::Response(2 elements)
+```
+
+##### transactions
+
+_n.b. transactions is a paged endpoint.  Take care to inspect `response.next_cursor` in case there's more data to be read._
+
+Along with the required account id, you may also pass the following optional arguments as a Hash as the second argument:
+
+* `:cursor` (String): An API cursor to fetch a specific set of results.
+* `:start` (ISO-8601 datetime String): Fetch transactions after this time.
+* `:end` (ISO-8601 datetime String): Fetch transactions before this time.
+
+```ruby
+require 'button'
+
+client = Button::Client.new('sk-XXX')
+
+response = client.accounts.transactions('acc-XXX')
+cursor = response.next_cursor
+
+puts response
+# => Button::Response(75 elements)
+
+# Unpage all results
+#
+while !cursor.nil? do
+  response = client.accounts.transactions('acc-XXX', cursor: cursor)
+  cursor = response.next_cursor
+end
+```
+
+### Merchants
+
+##### all
+
+You may also pass the following optional arguments as a Hash as the first argument:
+
+* `:status` (String): Partnership status to filter by. One of ('approved', 'pending', or 'available')
+* `:currency` (ISO-4217 String): Currency code to filter returned rates by
+
+```ruby
+require 'button'
+
+client = Button::Client.new('sk-XXX')
+
+response = client.merchants.all(status: 'pending', currency: 'GBP')
+
+puts response
+# => Button::Response(23 elements)
+```
 
 ### Orders
 
@@ -98,7 +166,7 @@ response = client.orders.create({
   btn_ref: 'srctok-XXX'
 })
 
-puts response 
+puts response
 # => Button::Response(button_order_id: btnorder-XXX, total: 50, ... )
 ```
 
@@ -111,9 +179,10 @@ client = Button::Client.new('sk-XXX')
 
 response = client.orders.get('btnorder-XXX')
 
-puts response 
+puts response
 # => Button::Response(button_order_id: btnorder-XXX, total: 50, ... )
 ```
+
 ##### Update
 
 ```ruby
@@ -123,7 +192,7 @@ client = Button::Client.new('sk-XXX')
 
 response = client.orders.update('btnorder-XXX', total: 60)
 
-puts response 
+puts response
 # => Button::Response(button_order_id: btnorder-XXX, total: 60, ... )
 ```
 
@@ -140,6 +209,38 @@ puts response
 # => Button::Response()
 ```
 
+## Response
+
+An instance of the `Button::Response` class will be returned by all API methods.  It is used to read the response data as well as collect any meta data about the response, like potential next and previous cursors to more data in a paged endpoint.
+
+### Methods
+
+#### data
+
+returns the underlying response data
+
+```ruby
+require 'button'
+
+client = Button::Client.new('sk-XXX')
+
+response = client.accounts.all
+
+puts response
+# => Button::Response(2 elements)
+
+puts response.data
+# => [ { ... }, { ... } ]
+```
+
+#### next_cursor
+
+For any paged resource, `#next_cursor` will return a cursor to supply for the next page of results.  If `#next_cursor` returns `nil`, then there are no more results.
+
+#### prev_cursor
+
+For any paged resource, `#prev_cursor` will return a cursor to supply for the previous page of results.  If `#prev_cursor` returns `nil`, then there are no more results, err.. backwards.
+
 ## Utils
 
 Utils houses generic helpers useful in a Button Integration.

data/lib/button/client.rb

@@ -1,3 +1,5 @@
+require 'button/resources/accounts'
+require 'button/resources/merchants'
 require 'button/resources/orders'
 require 'button/errors'
 
@@ -23,6 +25,8 @@ module Button
 
       config_with_defaults = merge_defaults(config)
 
+      @accounts = Accounts.new(api_key, config_with_defaults)
+      @merchants = Merchants.new(api_key, config_with_defaults)
       @orders = Orders.new(api_key, config_with_defaults)
     end
 
@@ -37,7 +41,7 @@ module Button
       }
     end
 
-    attr_reader :orders
+    attr_reader :accounts, :merchants, :orders
     private :merge_defaults
   end
 end

data/lib/button/resources/accounts.rb

@@ -0,0 +1,39 @@
+require 'button/resources/resource'
+
+module Button
+  # https://www.usebutton.com/developers/api-reference/
+  #
+  class Accounts < Resource
+    def path(account_id = nil)
+      return "/v1/affiliation/accounts/#{account_id}/transactions" if account_id
+      '/v1/affiliation/accounts'
+    end
+
+    # Gets a list of available accounts
+    #
+    # @return [Button::Response] the API response
+    #
+    def all
+      api_get(path)
+    end
+
+    # Gets a list of transactions for an account
+    #
+    # @param [String] account_id the account id to look up transactions for
+    # @option [String] cursor the account id to look up transactions for
+    # @option [ISO-8601 datetime String] start The start date to filter
+    #   transactions
+    # @option [ISO-8601 datetime String] end The end date to filter
+    #   transactions
+    # @return [Button::Response] the API response
+    #
+    def transactions(account_id, opts = {})
+      query = {}
+      query['cursor'] = opts[:cursor] if opts[:cursor]
+      query['start'] = opts[:start] if opts[:start]
+      query['end'] = opts[:end] if opts[:end]
+
+      api_get(path(account_id), query)
+    end
+  end
+end

data/lib/button/resources/merchants.rb

@@ -0,0 +1,23 @@
+require 'button/resources/resource'
+
+module Button
+  # https://www.usebutton.com/developers/api-reference/
+  #
+  class Merchants < Resource
+    # Gets a list of available merchants
+    #
+    # @option [String] status The status to filter by. One of ('approved',
+    #   'pending', or 'available')
+    # @option [ISO-4217 String] currency Currency code to filter returned rates
+    #   by
+    # @return [Button::Response] the API response
+    #
+    def all(opts = {})
+      query = {}
+      query['status'] = opts[:status] if opts[:status]
+      query['currency'] = opts[:currency] if opts[:currency]
+
+      api_get('/v1/merchants', query)
+    end
+  end
+end

data/lib/button/resources/resource.rb

@@ -1,3 +1,4 @@
+require 'uri'
 require 'net/http'
 require 'json'
 
@@ -43,10 +44,13 @@ module Button
     # Performs an HTTP GET at the provided path.
     #
     # @param [String] path the HTTP path
+    # @param [Hash=] query optional query params to send
     # @return [Button::Response] the API response
     #
-    def api_get(path)
-      api_request(Net::HTTP::Get.new(path))
+    def api_get(path, query = nil)
+      uri = URI(path)
+      uri.query = URI.encode_www_form(query) if query
+      api_request(Net::HTTP::Get.new(uri.to_s))
     end
 
     # Performs an HTTP POST at the provided path.
@@ -94,9 +98,11 @@ module Button
 
       raise ButtonClientError, "Invalid response: #{parsed}" unless parsed[:meta].is_a?(Hash)
 
-      status = parsed[:meta][:status]
+      meta = parsed[:meta]
+      status = meta[:status]
+      response_data = parsed.fetch(:object, parsed.fetch(:objects, {}))
 
-      return Response.new(parsed[:object]) if status == 'ok'
+      return Response.new(meta, response_data) if status == 'ok'
       raise ButtonClientError, "Unknown status: #{status}" unless status == 'error'
       raise ButtonClientError, parsed[:error][:message] if parsed[:error].is_a?(Hash)
       raise ButtonClientError, "Invalid response: #{parsed}"

data/lib/button/response.rb

@@ -1,3 +1,6 @@
+require 'cgi'
+require 'uri'
+
 module Button
   # Response is a simple proxy class for easy value unpacking from an API
   # response.  It is constructed with a hash and proxies method calls on the
@@ -5,33 +8,59 @@ module Button
   #
   # ## Usage
   #
-  # response = Button::Response.new({ :a => 1, :b => "two" })
-  # puts response.a
-  # puts response.to_hash
+  # response = Button::Response.new({
+  #   prev: 'https://bloop.net/?cursor=1989',
+  #   next: 'https://bloop.net/?cursor=1991'
+  # }, :a => 1, :b => "two")
+  #
+  # puts response.data
+  # puts response.next_cursor
+  # puts response.prev_cursor
   #
   class Response
-    def initialize(attrs)
-      @attrs = attrs || {}
+    def initialize(meta, response_data)
+      @meta = meta
+      @response_data = response_data
     end
 
     def to_s
-      values = @attrs.reduce([]) do |acc, (name, value)|
-        acc + ["#{name}: #{value || 'nil'}"]
-      end.join(', ')
+      repr = ''
+
+      if @response_data.is_a?(Hash)
+        repr = @response_data.reduce([]) do |acc, (name, value)|
+          acc + ["#{name}: #{value || 'nil'}"]
+        end.join(', ')
+      elsif @response_data.is_a?(Array)
+        repr = "#{@response_data.size} elements"
+      end
+
+      "Button::Response(#{repr})"
+    end
 
-      "Button::Response(#{values})"
+    def data
+      @response_data
     end
 
-    def to_hash
-      @attrs
+    def next_cursor
+      Response.format_cursor(@meta.fetch(:next, nil))
     end
 
-    def method_missing(attr)
-      @attrs[attr] || super
+    def prev_cursor
+      Response.format_cursor(@meta.fetch(:prev, nil))
     end
 
-    def respond_to_missing?(method_name, include_private = false)
-      @attrs.key?(method_name) || super
+    class << self
+      def format_cursor(cursor_url)
+        return nil unless cursor_url
+
+        parsed = URI(cursor_url)
+        return nil unless parsed.query
+
+        query = CGI.parse(parsed.query)
+        cursor = query.fetch('cursor', [])
+
+        cursor.empty? ? nil : cursor[0]
+      end
     end
   end
 end

data/lib/button/version.rb

@@ -1,3 +1,3 @@
 module Button
-  VERSION = '1.2.0'.freeze
+  VERSION = '2.0.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: button
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Button
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-04 00:00:00.000000000 Z
+date: 2017-01-06 00:00:00.000000000 Z
 dependencies: []
 description: Button is a contextual acquisition channel and closed-loop attribution
   and affiliation system for mobile commerce.
@@ -24,6 +24,8 @@ files:
 - lib/button.rb
 - lib/button/client.rb
 - lib/button/errors.rb
+- lib/button/resources/accounts.rb
+- lib/button/resources/merchants.rb
 - lib/button/resources/orders.rb
 - lib/button/resources/resource.rb
 - lib/button/response.rb
@@ -39,17 +41,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: ruby client for the Button Order API