synapse_pay_rest 0.0.15 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 47dd33491a54e460f6d819149c967607c7a93aaa
-  data.tar.gz: 409fe90ce07bb9eb0c99546cdb5d7c5d48c0e5e1
+  metadata.gz: e33376ac91a6d2f4824d884b3bec22a975285713
+  data.tar.gz: af00f3c6553a319bb4765d6299f1fa2c73c25860
 SHA512:
-  metadata.gz: 5b63b1214ab80b3e6647e4d9dab8c83c8dfde99f4902532f556a84538842b8643ddc3cf511c58d22946fb9c1b10d31abbb8ec454908519c6b8f8656db0718fa3
-  data.tar.gz: a08d5a5e82b14cbd9bd3cfb6116284e04833a2d8a33025c7fd077367ee1f938376817f1cc3388069cf1209776148a46d736f8eeeabd50e9bbb34c8d9df6fbad1
+  metadata.gz: afdb617d06b9c41c7c909ea2818fbaf7c38f4e5dc51b0dde52c01e785f263518b2c1d81fdb09c8a6ace160e47a8213090c4cad6ca381f320993c257742f75aa8
+  data.tar.gz: 5e9851313194faa3d6d806614247bf163f1253953f14cea6f004278797f76a627eeccd41c449b386a9f259713d8a4d7a968483070a47620b08f4c2c1f9e00eb5

data/.gitignore

@@ -9,6 +9,7 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
+coverage
 
 ## Specific to RubyMotion:
 .dat*
@@ -20,6 +21,7 @@ build/
 /_yardoc/
 /doc/
 /rdoc/
+*.html
 
 ## Environment normalisation:
 /.bundle/
@@ -35,6 +37,9 @@ build/
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
 
-
 .DS_Store
-.env
+
+## ENV variables and other secrets
+.env
+test.txt
+*.yml

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    synapse_pay_rest (0.0.13)
-      rest-client
+    synapse_pay_rest (2.0)
+      rest-client (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -12,8 +12,11 @@ GEM
     domain_name (0.5.20160826)
       unf (>= 0.0.5, < 1.0.0)
     dotenv (2.1.1)
-    http-cookie (1.0.2)
+    faker (1.6.6)
+      i18n (~> 0.5)
+    http-cookie (1.0.3)
       domain_name (~> 0.5)
+    i18n (0.7.0)
     mime-types (3.1)
       mime-types-data (~> 3.2015)
     mime-types-data (3.2016.0521)
@@ -39,9 +42,10 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.10)
-  dotenv
-  minitest
-  minitest-reporters
+  dotenv (~> 2.1.1)
+  faker (~> 1.6.6)
+  minitest (~> 5.8.2)
+  minitest-reporters (~> 1.1.5)
   rake (~> 10.0)
   synapse_pay_rest!
 

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 SynapsePay LLC
+
+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

@@ -1,34 +1,92 @@
-## SynapsePayRest-Ruby
+# SynapsePayRest-Ruby
 
-Simple API wrapper for SynapsePay REST V3 API.  This wrapper aims to handle the headers for each API request and appropriate error handling. Not all API endpoints are supported.
+Native API library for SynapsePay REST v3.x
 
-## Code Example
+Originally developed as a simple wrapper to handle the headers and endpoint URLs for each API request, as of v2.0.0 it now handles creation of User, Node, Transaction and related objects to remove the necessity of dealing with raw payload and response JSON.
 
-Check out [samples.md](https://github.com/synapsepay/SynapsePayRest-Ruby/blob/master/samples.md) and our [API documentation](http://docs.synapsepay.com/v3.1) for examples.
+Not all API endpoints are supported.
+
+**Pre-2.0.0 users**
+
+There are significant changes but backwards compatibility has been mostly maintained by building on top of the base API wrapper. You can still use the previous classes but note the following changes:
+
+- `ArgumentError` will be raised for missing payloads or other required arguments, where `RuntimeError` was raised previously. 
+- `development_mode` now defaults to true (gem previously defaulted to production).
+- KYC 1.0 methods for uploading documents have been deprecated. Please contact SynapsePay if you need to update to KYC 2.0.
+- API errors will now raise `SynapsePayRest::Error`s instead returning a JSON hash (and sometimes obfuscating the API error message).
 
 ## Installation
 
-gem install synapse_pay_rest
+Add this line to your application's Gemfile:
 
-## License
+```ruby
+gem 'synapse_pay_rest'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself by executing:
+
+```bash
+$ gem install synapse_pay_rest
+```
+
+## Documentation
+
+- [Samples demonstrating common operations](samples.md)
+- [Gem docs](http://www.rubydoc.info/gems/synapse_pay_rest)
+- [API docs](http://docs.synapsepay.com/v3.1)
+
+## Contributing
 
-The MIT License (MIT)
+Just open a pull request. Please document and test any public constants/methods. Open an issue or email steven@synapsepay.com if you have any questions.
 
-Copyright (c) 2014 SynapsePay LLC
+## Running the Test Suite
 
-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:
+Make sure these values are set as enviroment variables (using [dotenv](https://github.com/bkeepers/dotenv) for example):
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+```
+CLIENT_ID=your_sandbox_client_id
+CLIENT_SECRET=your_sandbox_client_secret
+```
+
+To run all tests, execute:
+
+```bash
+rake
+```
+
+To run a specific test or file, install the [m](https://github.com/qrush/m) gem and execute:
+
+```bash
+m path/to/file:line_number
+```
+
+## Todos
+
+- Smartly update the existing instances with response data instead of re-instantiating for every response. I started with this approach but it gets pretty complicated with the interconnected models of User/BaseDocument/Document. Also, certain values are only known if the user created an object, but not when the object is built from API response data. This is solveable but requires more dev time and testing.
+- Various factory helper methods should be private but are public. Would be good to refactor in a way that they can be private.
+- `User`/`Node`/`Transaction` have similar REST methods that could probably be factored into a superclass or module.
+- Use mixins instead of inheritance for the shared behavior of `Node`s and `Document`s. The parent classes are never instantiated anyways.
+- Refactor the redundant code in each `Node` type's version of `#payload_for_create`.
+- Better way to handle bank MFA nodes? Virtual doc KBA?
+- Add an option for logging responses in addition to requests.
+- Organize tests better.
+- Use mocked responses whenever possible in tests.
+- More examples.
+- More Error types (bad MFA answer, for example).
+- Add some methods to BaseDocument to return doc by type (e.g. `base_document.ssn_doc`).
+
+Specific todos are marked throughout in this format:
+
+```ruby
+# @todo Description of todo.
+```
+
+## License
 
-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.
+[MIT License](LICENSE)

data/lib/synapse_pay_rest.rb

@@ -1,25 +1,69 @@
-require "synapse_pay_rest/http_client"
-require "synapse_pay_rest/error"
-require "synapse_pay_rest/version"
-require "synapse_pay_rest/api/users"
-require "synapse_pay_rest/api/nodes"
-require "synapse_pay_rest/api/trans"
+# client classes
+require 'synapse_pay_rest/client'
+require 'synapse_pay_rest/http_client'
 
+# base API classes
+require 'synapse_pay_rest/api/users'
+require 'synapse_pay_rest/api/nodes'
+require 'synapse_pay_rest/api/transactions'
+
+# general library classes
+require 'synapse_pay_rest/error'
+require 'synapse_pay_rest/version'
+
+# user-related classes
+require 'synapse_pay_rest/models/user/user'
+require 'synapse_pay_rest/models/user/base_document'
+require 'synapse_pay_rest/models/user/document'
+require 'synapse_pay_rest/models/user/physical_document'
+require 'synapse_pay_rest/models/user/social_document'
+require 'synapse_pay_rest/models/user/virtual_document'
+require 'synapse_pay_rest/models/user/question'
+
+# node-related classes
+
+# ancestor of all BaseNodes
+require 'synapse_pay_rest/models/node/base_node'
+
+# BaseNode subclasses
+# synapse
+require 'synapse_pay_rest/models/node/synapse_node'
+require 'synapse_pay_rest/models/node/synapse_us_node.rb'
+require 'synapse_pay_rest/models/node/synapse_ind_node.rb'
+require 'synapse_pay_rest/models/node/synapse_np_node.rb'
+# ach
+require 'synapse_pay_rest/models/node/ach_us_node.rb'
+require 'synapse_pay_rest/models/node/unverified_node.rb'
+# eft
+require 'synapse_pay_rest/models/node/eft_node'
+require 'synapse_pay_rest/models/node/eft_ind_node.rb'
+require 'synapse_pay_rest/models/node/eft_np_node.rb'
+# wire
+require 'synapse_pay_rest/models/node/wire_node.rb'
+require 'synapse_pay_rest/models/node/wire_us_node.rb'
+require 'synapse_pay_rest/models/node/wire_int_node.rb'
+# reserve
+require 'synapse_pay_rest/models/node/reserve_us_node.rb'
+# iou
+require 'synapse_pay_rest/models/node/iou_node.rb'
+
+# BaseNode factory
+require 'synapse_pay_rest/models/node/node'
+
+# transaction-related classes
+require 'synapse_pay_rest/models/transaction/transaction'
+
+# Namespace for all SynapsePayRest classes and modules
 module SynapsePayRest
-  class Client
-    attr_accessor :client, :users, :nodes, :trans
-
-    def initialize(options: raise("options is required"), user_id: nil)
-      base_url = if options['development_mode']
-                   'https://sandbox.synapsepay.com/api/3'
-                 else
-                   'https://synapsepay.com/api/3'
-                 end
-
-      @client = HTTPClient.new options, base_url, user_id: user_id
-      @users = Users.new @client
-      @nodes = Nodes.new @client
-      @trans = Trans.new @client
-    end
+  # Modifies the default method to print a warning when deprecated constants
+  # used and returns the new constant.
+  #
+  # @param [Constant]
+  # @return [Constant] the corresponding constant that is not deprecated.
+  def self.const_missing(const_name)
+    super unless const_name == :Trans
+    warn caller.first + " DEPRECATION WARNING: the class SynapsePayRest::#{const_name}"\
+                        'is deprecated. Use SynapsePayRest::Transactions instead.'
+    Transactions
   end
 end

data/lib/synapse_pay_rest/api/nodes.rb

@@ -1,45 +1,119 @@
 module SynapsePayRest
+  # Wrapper class for /nodes endpoints
   class Nodes
+    # Valid optional args for #get
+    # @todo Should refactor this to HTTPClient
+    VALID_QUERY_PARAMS = [:page, :per_page, :type].freeze
+
+    # @!attribute [rw] client
+    #   @return [SynapsePayRest::HTTPClient]
     attr_accessor :client
 
+    # @param [SynapsePayRest::HTTPClient]
     def initialize(client)
       @client = client
     end
 
-    def create_node_path(node_id: nil)
-      path = ['/users', client.user_id, 'nodes' ]
-      path << node_id if node_id
-      path.join('/')
+    # Sends a GET request to /nodes endpoint. Queries a specific node_id if
+    # node_id supplied, else queries all nodes. Returns the response.
+    # 
+    # @param node_id [String] id of the node
+    # @param page [String,Integer] (optional) response will default to 1
+    # @param per_page [String,Integer] (optional) response will default to 20
+    # @param type [String] (optional)
+    # @see https://docs.synapsepay.com/docs/node-resources node types
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    # 
+    # @todo should use CGI or RestClient's param builder instead of
+    #   rolling our own, probably error-prone and untested
+    #   https://github.com/rest-client/rest-client#usage-raw-url
+    def get(node_id: nil, **options)
+      params = VALID_QUERY_PARAMS.map do |p|
+        options[p] ? "#{p}=#{options[p]}" : nil
+      end.compact
+
+      path = create_node_path(node_id: node_id)
+      path += '?' + params.join('&') if params.any?
+      client.get(path)
     end
 
-    def add(payload: raise("payload is required"))
+    # Sends a POST request to /nodes endpoint, to create a new node for the
+    # current user, and returns the response.
+    # 
+    # @param payload [Hash] format depends on node type 
+    # @see https://docs.synapsepay.com/docs/node-resources payload structure
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def post(payload:)
       path = create_node_path
       client.post(path, payload)
     end
 
-    def get(node_id: nil, page: nil)
-      # If node_id is nil then create_node_path will handle it just fine
+    # Alias for #post (legacy name)
+    alias_method :add, :post
+
+    # Sends a PATCH request to /nodes endpoint to update a node, and returns the
+    # response. Only used to verify microdeposits for ACH-US nodes currently.
+    # 
+    # @param node_id [String] id of the node
+    # @param payload [Hash]
+    # @see https://docs.synapsepay.com/docs/verify-micro-deposit payload structure
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def patch(node_id:, payload:)
       path = create_node_path(node_id: node_id)
-      path += "?page=#{page}" if page
-      client.get(path)
+      @client.patch(path, payload)
     end
 
-    # separate this into different methods
-    def verify(node_id: nil, payload: raise("payload is required"))
+    # Sends a DELETE request to /node endpoint to remove a node, and returns the response.
+    # 
+    # @param node_id [String] id of the node
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def delete(node_id:)
+      path = create_node_path(node_id: node_id)
+      client.delete(path)
+    end
+
+    # Verifies microdeposits (via #patch) for a node if a node_id supplied, else
+    # submits answers to bank login MFA questions (via #post).
+    # 
+    # @param node_id [String] id of the node
+    # @param payload [Hash] see #patch and #post for payload format
+    # @deprecated Use #update for microdeposit verification or #post for MFA answers.
+    def verify(node_id: nil, payload:)
       if node_id
+        warn caller.first + " DEPRECATION WARNING: #{self.class}##{__method__} is deprecated. Use #patch instead."
+
         # verify microdeposits
-        path = create_node_path(node_id: node_id)
-        response = @client.patch(path, payload)
+        patch(node_id: node_id, payload: payload)
       else
-        # verify MFA question(s)
-        path = create_node_path
-        response = @client.post(path, payload)
+        warn caller.first + " DEPRECATION WARNING: #{self.class}##{__method__} is deprecated. Use #post instead."
+
+        # verify MFA questions
+        post(payload: payload)
       end
     end
 
-    def delete(node_id: raise("node_id is required"))
-      path = create_node_path(node_id: node_id)
-      client.delete(path)
+    private
+
+    def create_node_path(node_id: nil)
+      path = ['/users', client.user_id, 'nodes' ]
+      path << node_id if node_id
+      path.join('/')
     end
   end
 end

data/lib/synapse_pay_rest/api/transactions.rb

@@ -0,0 +1,103 @@
+module SynapsePayRest
+  # Wrapper class for /trans endpoints
+  # 
+  # @todo Implement idempotency keys
+  class Transactions
+
+    # Valid optional args for #get
+    # @todo Refactor to HTTPClient
+    VALID_QUERY_PARAMS = [:page, :per_page].freeze
+
+    # @!attribute [rw] client
+    #   @return [SynapsePayRest::HTTPClient]
+    attr_accessor :client
+
+    # @param client [SynapsePayRest::HTTPClient]
+    def initialize(client)
+      @client = client
+    end
+
+    # Sends a GET request to /trans endpoint. Queries a specific transaction_id
+    # if trans_id supplied, else queries all transactions. Returns the response.
+    # 
+    # @param node_id [String] id of the from node
+    # @param trans_id [String,void] (optional) id of a transaction to look up
+    # @param page [String,Integer] (optional) response will default to 1
+    # @param per_page [String,Integer] (optional) response will default to 20
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    # 
+    # @todo Probably should use CGI or RestClient's param builder instead of
+    # rolling our own, probably error-prone and untested version
+    # https://github.com/rest-client/rest-client#usage-raw-url
+    def get(node_id:, trans_id: nil, **options)
+      path = create_transaction_path(node_id: node_id, trans_id: trans_id)
+
+      params = VALID_QUERY_PARAMS.map do |p|
+        options[p] ? "#{p}=#{options[p]}" : nil
+      end.compact
+
+      path += '?' + params.join('&') if params.any?
+      client.get(path)
+    end
+
+    # Sends a POST request to /trans endpoint to create a new transaction.
+    # Returns the response.
+    # 
+    # @param node_id [String] id of the from node
+    # @param payload [Hash]
+    # @see https://docs.synapsepay.com/docs/create-transaction payload structure
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def create(node_id:, payload:)
+      path = create_transaction_path(node_id: node_id)
+      client.post(path, payload)
+    end
+
+    # Sends a PATCH request to /trans endpoint to update a transaction. 
+    # Returns the response.
+    # 
+    # @param node_id [String] id of the from node
+    # @param trans_id [String] id of a transaction to update
+    # @param payload [Hash]
+    # @see https://docs.synapsepay.com/docs/update-transaction payload structure
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def update(node_id:, trans_id:, payload:)
+      path = create_transaction_path(node_id: node_id, trans_id: trans_id)
+      client.patch(path, payload)
+    end
+
+    # Sends a DELETE request to /trans endpoint to cancel a transaction.
+    # Returns the response.
+    # 
+    # @param node_id [String] id of the from node
+    # @param trans_id [String] id of a transaction to delete
+    # 
+    # @raise [SynapsePayRest::Error] may return subclasses of error based on 
+    # HTTP response from API
+    # 
+    # @return [Hash] API response
+    def delete(node_id:, trans_id:)
+      path = create_transaction_path(node_id: node_id, trans_id: trans_id)
+      client.delete(path)
+    end
+
+    private
+
+    def create_transaction_path(node_id:, trans_id: nil)
+      path = ['/users', client.user_id, 'nodes', node_id, 'trans' ]
+      path << trans_id if trans_id
+      return path.join('/')
+    end
+  end
+end