starling-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7792e100b4e4f2815be54969b6f93eb7dc462cea
-  data.tar.gz: 39494875175595c11bd964e26d3790332e863dca
+  metadata.gz: b8a9d85c10f82c31df8e74a368d3180e01d16d76
+  data.tar.gz: b844476947553b58c50ad54e927746bf21978af1
 SHA512:
-  metadata.gz: e82c0ca11d00d1665fdbc5feea79817dfb77065796905a05ffc15a33985db6e7621bdf4763133e7b484f92d565905195b5d48b5ef6dde7d823223861655a9f50
-  data.tar.gz: 612492a35d4de1bb25e8d9d8a01abd3bca0edecc5f04a29a33bda3ab7417c12b5dc8e48fc0005a723c984e289fe03c4406df5f3385a0959f88983fd80293bc52
+  metadata.gz: df6103bb3533d7d5ae0abccf312c3939f5c06c07cf49fe19fd502274c969798ea33691ffa217e6fee52c2c670d29ff5b27cfef47aa245d7107b305e21330d85a
+  data.tar.gz: 10c9a6efe88bf5f4b65654513d7e2aae5ce9a96230a39b51887d5764274f9ab5cb35ffddb8fa16a197402b6b29b23d35762203e7ef7c7f02cbe0265f2562e278

data/.circleci/config.yml

@@ -11,6 +11,9 @@ jobs:
       - type: cache-restore
         key: starling-{{ checksum "Gemfile.lock" }}
 
+      # Update bundler
+      - run: gem install bundler
+
       # Bundle install dependencies
       - run: bundle install --path vendor/bundle
 
@@ -34,6 +37,11 @@ jobs:
         command: |
           bundle exec rubocop
 
+      # Run Reek
+      - type: shell
+        command: |
+          bundle exec reek lib
+
       # Save artifacts
       - type: store_test_results
         path: /tmp/test-results

data/.gitignore

@@ -8,3 +8,4 @@
 /tmp/
 /vendor
 .rspec_status
+*.gem

data/.reek

@@ -0,0 +1,27 @@
+UtilityFunction:
+  public_methods_only: true
+
+IrresponsibleModule:
+  enabled: false
+
+TooManyInstanceVariables:
+  exclude:
+    - "Starling::Request"
+
+LongParameterList:
+  max_params: 4
+  exclude:
+    - "Starling::ApiService#make_request"
+
+DataClump:
+  min_clump_size: 4
+
+ControlParameter:
+  exclude:
+    # This looks like a false positive to me! `parsed_data` doesn't control the method.
+    - "Starling::Resources::BaseResource#initialize"
+
+TooManyMethods:
+  exclude:
+    # Starling::Client has to have lots of methods, since it has one for each service
+    - "Starling::Client"

data/.rubocop.yml

@@ -3,10 +3,12 @@ AllCops:
 
 Metrics/LineLength:
   Max: 90
-
-Style/Documentation:
-  Enabled: false
+  Exclude:
+    # We have a very long line in this file in our YARD documentation comments to link to
+    # a PDF on the MasterCard website. This can't be broken into separate lines, and
+    # adding a rubocop:disable comment appears in the docs, so let's disable it here.
+    - lib/starling/resources/merchant_location_resource.rb
 
 Metrics/BlockLength:
   Exclude:
-  - spec/**/*
+    - spec/**/*

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## v0.2.0 - 4 Jun 2017
+
+* Add support for the Transaction Faster Payments In, Transaction Faster Payments Out,
+Transaction Direct Debit, Payment and Transaction Mastercard APIs
+* Improve error handling behaviour to raise errors at the right time with clear,
+accessible information about what went wrong
+* Use Ruby 2.0+ keyword arguments rather than passing around `Hash`es
+* Add full [YARD](http://yardoc.org/) documentation
+* Consistently return `Float`s for all API attributes which can be integers or floats
+* Refactor `Request` to remove private methods
+* Refactor `Resources::BaseResource`
+* Check for common code smells with [Reek](https://github.com/troessner/reek) as part of
+the CI process
+
+## v0.1.0 - 30 May 2017
+
+* Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    starling-ruby (0.1.0)
+    starling-ruby (0.2.0)
       faraday (>= 0.8.9, < 0.10)
 
 GEM
@@ -10,14 +10,27 @@ GEM
     addressable (2.5.1)
       public_suffix (~> 2.0, >= 2.0.2)
     ast (2.3.0)
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
     builder (3.2.3)
+    codeclimate-engine-rb (0.4.0)
+      virtus (~> 1.0)
     coderay (1.1.1)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.3)
+    equalizer (0.0.11)
     faraday (0.9.2)
       multipart-post (>= 1.2, < 3)
+    ffi (1.9.18-java)
     hashdiff (0.3.4)
+    ice_nine (0.11.2)
     method_source (0.8.2)
     multipart-post (2.0.0)
     parallel (1.11.2)
@@ -28,10 +41,19 @@ GEM
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
+    pry (0.10.4-java)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+      spoon (~> 0.0)
     public_suffix (2.0.5)
     rainbow (2.2.2)
       rake
     rake (10.5.0)
+    reek (4.7.0)
+      codeclimate-engine-rb (~> 0.4.0)
+      parser (>= 2.4.0.0, < 2.5)
+      rainbow (~> 2.0)
     rspec (3.6.0)
       rspec-core (~> 3.6.0)
       rspec-expectations (~> 3.6.0)
@@ -61,20 +83,32 @@ GEM
     ruby-progressbar (1.8.1)
     safe_yaml (1.0.4)
     slop (3.6.0)
+    spoon (0.0.6)
+      ffi
+    thread_safe (0.3.6)
+    thread_safe (0.3.6-java)
     unicode-display_width (1.2.1)
     values (1.8.0)
+    virtus (1.0.5)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0, >= 0.0.3)
+      equalizer (~> 0.0, >= 0.0.9)
     webmock (3.0.1)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff
+    yard (0.8.7.6)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
   bundler (~> 1.14)
   pry (~> 0.10.4)
   rake (~> 10.0)
+  reek (~> 4.7.0)
   rspec (~> 3.0)
   rspec-its (~> 1.2.0)
   rspec_junit_formatter (~> 0.2.3)
@@ -82,6 +116,7 @@ DEPENDENCIES
   starling-ruby!
   values (~> 1.8.0)
   webmock (~> 3.0.1)
+  yard (~> 0.8.7.6)
 
 BUNDLED WITH
-   1.15.0
+   1.15.1

data/README.md

@@ -3,17 +3,28 @@
 The Starling Ruby library provides a simple, idiomatic interface to the [Starling Bank API](https://developer.starlingbank.com).
 
 [![CircleCI](https://circleci.com/gh/timrogers/starling-ruby/tree/master.svg?style=svg)](https://circleci.com/gh/timrogers/starling-ruby/tree/master)
+[![Gem Version](https://badge.fury.io/rb/starling-ruby.svg)](https://badge.fury.io/rb/starling-ruby)
 
 ## Getting started
 
 Install the gem by adding it to your Gemfile, and then run `bundle`:
 
 ```ruby
-# The gem will be available on RubyGems soon 💎
-gem 'starling-ruby', github: "timrogers/starling-ruby"
+gem 'starling-ruby', '~> 0.2.0', require: 'starling'
 ```
 
-You can now initialise the client, providing an access token, an optionally an environment (either `:sandbox` or `:production`, defaulting to :production):
+You'll need to get a personal access token for your Starling account. To get set up,
+head to the Starling Developers 
+["Get Started" page](https://developer.starlingbank.com/get-started) and then scroll
+down to the "Personal Access" section for instructions.
+
+At the moment, the library is not designed to
+support OAuth applications (it can't handle refreshing access tokens) or endpoints
+requiring the [`pay-local:create` scope](https://developer.starlingbank.com/tiers),
+which is not granted to personal access tokens.
+
+You can now initialise the client, providing your access token, and optionally an
+environment (either `:sandbox` or `:production`, defaulting to :production):
 
 ```ruby
 starling = Starling::Client.new(
@@ -25,11 +36,15 @@ starling = Starling::Client.new(
 
 ## Usage
 
-Once you've initialised a `Starling::Client`, it exposes a number of services (living
-in `lib/starling/services`) which have methods calling out to the API, and returning
-resources (found in `lib/starling/resources`).
+Now you've initialised a `Starling::Client` with your access token, you can start making
+requests to the API. 
+
+All APIs are supported except "Get Photo" under the Contact API (it doesn't seem to
+actually be possible to set a photo...) and the Payment APIs for creating an immediate or scheduled payment (which are not supported for personal access tokens).
 
-Much of the API has not yet been implemented. Stay tuned for further updates ❤️
+See below for a few simple examples, or head to our
+[full documentation](http://www.rubydoc.info/github/timrogers/starling-ruby/master) for
+complete details:
 
 ### Check your balance
 
@@ -42,14 +57,16 @@ puts "Your balance is #{balance.amount} #{balance.currency}!"
 
 ```ruby
 account = starling.account.get
-puts "Your sort code is #{account.sort_code} and your account number is #{account.number}."
+puts "Your sort code is #{account.sort_code} and your account number is " \
+     "#{account.number}."
 ```
 
 ### List transactions
 
 ```ruby
 transaction = starling.transactions.list.first
-puts "Your most recent transaction was for #{transaction.amount} on #{transaction.created}"
+puts "Your most recent transaction was for #{transaction.amount} on " \
+     "#{transaction.created}"
 ```
 
 ### Fetch a transaction by ID
@@ -59,27 +76,95 @@ transaction = starling.transactions.get("insert-uuid-here")
 puts "Your transaction was for #{transaction.amount} on #{transaction.created}"
 ```
 
+### Fetch a merchant by ID
+
+```ruby
+merchant = starling.merchants.get("insert-uuid-here")
+puts "You can call #{merchant.name} on #{merchant.phone_number}"
+```
+
+### Fetch a merchant location by ID
+
+```ruby
+merchant_location = starling.merchant_locations.get(
+  "insert-merchant-uid-here",
+  "insert-merchant-location-uid-here"
+)
+
+puts "This location for #{merchant_location.merchant_name} is called " \
+     "#{merchant_location.location_name}"
+```
+
+## Philosophy
+
+Once you've initialised a `Starling::Client`, it exposes a number of services (living
+in `lib/starling/services`) which have methods calling out to the API. 
+
+Philosophically, these services represent "kinds of things" (i.e. resources) returned by 
+or manipulated by the API. __These do not necessarily match up with the APIs listed in
+Starling's [documentation](https://developer.starlingbank.com/docs), which is grouped slightly differently__. 
+
+The benefit is that we can have a small, predictable set of methods in our
+services exposing API endpoints: `#get`, `#list`, `#create` and `#delete`. 
+
+This is best shown through an example - let's look at the Merchant API. It has two
+endpoints listed under it: "Get Merchant" and "Get Location". The former operates on
+a "kind of thing" called a "contact", and the latter operates on a "kind of thing" called
+a "contact account". You could potentially group these together, but then you'd have to
+have a slightly odd method name (something like `get_location`). Instead, we keep things
+consistent, like follows:
+
+```ruby
+starling.merchants.get(merchant_id)
+starling.merchant_locations.get(merchant_id, merchant_location_id)
+```
+
+Other parts of the Starling Bank API exhibit similar difficulties - for example, the
+Contact API operates on Contacts, Contact Accounts and Contact Photos.
+
+Methods on the services for accessing the API return resources (found in
+`lib/starling/resources`), arrays of resources or, rarely, `Faraday::Response`s in the
+case of `DELETE` requests.
+
+## Backwards compatability
+
+This gem is versioned using [Semantic Versioning](http://semver.org/), so you can be
+confident when updating that there will not be breaking changes outside of a major
+version (following format MAJOR.MINOR.PATCH, so for instance moving from 2.3.0 to 3.0.0
+would be allowed to include incompatible API changes). See
+[CHANGELOG.md](https://github.com/timrogers/starling-ruby/tree/master/CHANGELOG.md) for
+details on what has changed in each version.
+
+Until we reach v1.0, minor versions may contain backwards-incompatible changes, as the
+API stabilises. Any such changes will be flagged in the changelog.
+
 ## Tests
 
-The recommended way to run tests on the project is using CircleCI's local Docker testing
-- this is the best way to make sure that what passes tests locally in development will
-work when you push it and it runs through our automated CI.
+The recommended way to run tests on the project is using CircleCI's local Docker
+testing - this is the best way to make sure that what passes tests locally in development
+will work when you push it and it runs through our automated CI.
 
 ```bash
 # Download the circleci binary (assuming /usr/local/bin is in your PATH)
-curl -o /usr/local/bin/circleci https://circle-downloads.s3.amazonaws.com/releases/build_agent_wrapper/circleci && chmod +x /usr/local/bin/circleci
+curl -o /usr/local/bin/circleci \
+https://circle-downloads.s3.amazonaws.com/releases/build_agent_wrapper/circleci
+
+chmod +x /usr/local/bin/circleci
 
-# Run the full CI process, including tests and Rubocop. You'll need Docker installed.
+# Run the full CI process, including tests, Rubocop and Reek. You'll need Docker
+# installed.
 circleci build
 ```
 
-You can also run tests in your own environment by running `bundle exec rake`, and can
-run Rubocop by running `bundle exec rubocop`.
+You can also run tests in your own environment by running `bundle exec rake`, can
+run Rubocop by running `bundle exec rubocop` and can run Reek by running `bundle exec
+reek lib`.
 
 ## Contributing
 
 All contributions are welcome - just make a pull request, making sure you include tests
-and write a good, informative commit message/pull request body.
+and documentation for any public methods, and write a good, informative commit
+message/pull request body.
 
 Check out
 [CODE_OF_CONDUCT.md](https://github.com/timrogers/starling-ruby/blob/master/CODE_OF_CONDUCT.md)

data/bin/console

@@ -6,9 +6,5 @@ require 'starling'
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)
+require 'pry'
+Pry.start

data/lib/starling.rb

@@ -1,18 +1,51 @@
+require 'starling/utils'
 require 'starling/version'
-require 'starling/client'
-require 'starling/api_service'
 require 'starling/request'
+require 'starling/api_service'
+require 'starling/client'
 require 'starling/errors/base_error'
 require 'starling/errors/api_error'
 require 'starling/middlewares/raise_starling_errors'
-require 'starling/services/base_service'
-require 'starling/services/account_service'
-require 'starling/services/account_balance_service'
-require 'starling/services/transactions_service'
+
 require 'starling/resources/base_resource'
-require 'starling/resources/account_resource'
 require 'starling/resources/account_balance_resource'
+require 'starling/resources/account_resource'
+require 'starling/resources/address_resource'
+require 'starling/resources/addresses_resource'
+require 'starling/resources/card_resource'
+require 'starling/resources/contact_account_resource'
+require 'starling/resources/contact_resource'
+require 'starling/resources/customer_resource'
+require 'starling/resources/direct_debit_mandate_resource'
+require 'starling/resources/direct_debit_transaction_resource'
+require 'starling/resources/inbound_faster_payments_transaction_resource'
+require 'starling/resources/mastercard_transaction_resource'
+require 'starling/resources/me_resource'
+require 'starling/resources/merchant_location_resource'
+require 'starling/resources/merchant_resource'
+require 'starling/resources/outbound_faster_payments_transaction_resource'
+require 'starling/resources/payment_resource'
 require 'starling/resources/transaction_resource'
 
+require 'starling/services/base_service'
+require 'starling/services/account_balance_service'
+require 'starling/services/account_service'
+require 'starling/services/addresses_service'
+require 'starling/services/card_service'
+require 'starling/services/contact_accounts_service'
+require 'starling/services/contacts_service'
+require 'starling/services/customer_service'
+require 'starling/services/direct_debit_mandates_service'
+require 'starling/services/direct_debit_transactions_service'
+require 'starling/services/inbound_faster_payments_transactions_service'
+require 'starling/services/mastercard_transactions_service'
+require 'starling/services/me_service'
+require 'starling/services/merchant_locations_service'
+require 'starling/services/merchants_service'
+require 'starling/services/outbound_faster_payments_transactions_service'
+require 'starling/services/payments_service'
+require 'starling/services/transactions_service'
+
+# A Ruby client for accessing the Starling Bank API
 module Starling
 end

data/lib/starling/api_service.rb

@@ -1,31 +1,57 @@
 require 'faraday'
 
 module Starling
+  # The API client under the hood, used by services publicly exposed by
+  # {Starling::Client} to dispatch requests to the Starling Bank API
   class ApiService
+    # The default adapter which will be used by Faraday to make requests. This can be
+    # customised by passing a :http_adapter when instantiating the ApiService.
     DEFAULT_ADAPTER = :net_http
-    BASE_PATH = '/api/v1'.freeze
-
-    def initialize(base_url, options = {})
-      @access_token = options.fetch(:access_token)
 
-      http_adapter = options[:http_adapter] || [DEFAULT_ADAPTER]
-      connection_options = options[:connection_options]
+    # The path of the API version which will be prepended to request paths
+    BASE_PATH = '/api/v1'.freeze
 
+    # Instantiates a {ApiService} for dispatching requests to the Starling Bank API
+    #
+    # @param base_url [String] The base URL for the Starling API, including the protocol
+    #                          and hostname, to which the {BASE_PATH} and request paths
+    #                          will be added
+    # @param access_token [String] A personal access token for the Starling Bank API
+    # @param http_adapter [Array] The HTTP adapter to be used, defaulting to
+    #                             {DEFAULT_ADAPTER}
+    # @param connection_options [Hash] A hash of options to be passed in when
+    #                                  instantiating Faraday (for example for setting
+    #                                  the request timeout)
+    # @param default_headers [Hash] A set of user-provided HTTP headers to add to each
+    #                               request, alongside the library's defaults defined in
+    #                               {#library_default_headers}
+    # @return [Starling::ApiService] The configured ApiService
+    def initialize(base_url, access_token:, http_adapter: [DEFAULT_ADAPTER],
+                   connection_options: {}, default_headers: {})
       @connection = Faraday.new(base_url, connection_options) do |faraday|
         faraday.response(:raise_starling_errors)
         faraday.adapter(*http_adapter)
       end
 
-      user_provided_default_headers = options.fetch(:default_headers, {})
-      @headers = default_headers.merge(user_provided_default_headers)
+      @headers = library_default_headers(access_token: access_token)
+                 .merge(default_headers)
     end
 
-    def make_request(method, path, options = {})
-      raise ArgumentError, 'options must be a hash' unless options.is_a?(Hash)
-      options[:headers] ||= {}
-      options[:headers] = @headers.merge(options[:headers])
-
-      Request.new(@connection, method, build_path(path), options)
+    # Makes an HTTP request to the Starling Bank API with the specified method and path
+    #
+    # @param method [Symbol] The HTTP method which will be used for the request
+    # @param path [String] The path of the API endpoint, which will be appended to the
+    #                      {BASE_PATH}
+    # @param params [Hash] The parameters which will be included in the request, either
+    #                      in the URL or the body, depending on the method
+    # @param headers [Hash] Additional headers to be included in your request, which will
+    #                       be merged on top of the service's default headers
+    # @return [Faraday::Response] The response from the server to the dispatched request
+    def make_request(method, path, params: {}, headers: {})
+      headers = @headers.merge(headers)
+
+      Request.new(@connection, method, build_path(path), params: params,
+                                                         headers: headers)
              .make_request
     end
 
@@ -35,9 +61,9 @@ module Starling
       "#{BASE_PATH}#{path}"
     end
 
-    def default_headers
+    def library_default_headers(access_token:)
       {
-        'Authorization' => "Bearer #{@access_token}",
+        'Authorization' => "Bearer #{access_token}",
         'Accept' => 'application/json',
         'User-Agent' => user_agent
       }
@@ -47,32 +73,14 @@ module Starling
       @user_agent ||=
         begin
           comment = [
-            "#{ruby_engine}/#{ruby_version}",
-            "#{RUBY_ENGINE}/#{interpreter_version}",
+            "#{Utils.ruby_engine}/#{Utils.ruby_version}",
+            "#{RUBY_ENGINE}/#{Utils.interpreter_version}",
             RUBY_PLATFORM.to_s,
             "faraday/#{Faraday::VERSION}"
           ]
 
-          "#{gem_info} #{comment.join(' ')}"
+          "#{Utils.gem_info} #{comment.join(' ')}"
         end
     end
-
-    def gem_info
-      return 'starling-ruby' unless defined?(Starling::VERSION)
-      "starling-ruby/v#{Starling::VERSION}"
-    end
-
-    def ruby_engine
-      defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'
-    end
-
-    def ruby_version
-      return RUBY_VERSION unless defined?(RUBY_PATCHLEVEL)
-      RUBY_VERSION + "p#{RUBY_PATCHLEVEL}"
-    end
-
-    def interpreter_version
-      defined?(JRUBY_VERSION) ? JRUBY_VERSION : RUBY_VERSION
-    end
   end
 end