starling-ruby 0.1.0 → 0.2.0

data/lib/starling/client.rb

@@ -1,33 +1,192 @@
 require 'uri'
 
 module Starling
+  # The client for the Starling Bank API, providing authenticated access to the various
+  # endpoints offered in the API, with a uniform, idiomatic Ruby interface.
   class Client
+    # URLs for the two Starling Bank API environments, production and sandbox
     ENVIRONMENT_BASE_URLS = {
       production: 'https://api.starlingbank.com',
       sandbox: 'https://api-sandbox.starlingbank.com'
     }.freeze
 
-    def initialize(options = {})
-      raise ArgumentError, 'access_token must be provided' unless options[:access_token]
-
-      environment = options.delete(:environment) { :production }
-
+    # Instantiates a client for accessing the Starling Bank API
+    #
+    # @param access_token [String] A personal access token for the Starling Bank API
+    # @param environment [Symbol] The API environment to use, either :production or
+    #                             :sandbox
+    # @param default_headers [Hash] A set of HTTP headers to add to each request,
+    #                               alongside the library's defaults defined in
+    #                               {Starling::ApiService#library_default_headers}
+    # @param connection_options [Hash] A hash of options to be passed in when
+    #                                  instantiating Faraday (for example for setting
+    #                                  the request timeout)
+    # @return [Starling::Client] the configured Starling client
+    def initialize(access_token:, environment: :production, default_headers: {},
+                   connection_options: {})
       @api_service = ApiService.new(fetch_base_url_for_environment(environment),
-                                    options)
+                                    access_token: access_token,
+                                    default_headers: default_headers,
+                                    connection_options: connection_options)
     end
 
+    # Provides access to the Account API
+    #
+    # @return [Starling::Services::AccountService] a configured service for accessing the
+    #                                              Account API
     def account
       Services::AccountService.new(@api_service)
     end
 
+    # Provides access to the Account Balance API
+    #
+    # @return [Starling::Services::AccountBalanceService] a configured service for
+    #                                                     accessing the Account Balance
+    #                                                     API
     def account_balance
       Services::AccountBalanceService.new(@api_service)
     end
 
+    # Provides access to the Transactions API
+    #
+    # @return [Starling::Services::TransactionsService] a configured service for
+    #                                                   accessing the Transactions API
     def transactions
       Services::TransactionsService.new(@api_service)
     end
 
+    # Provides access to the Merchants API
+    #
+    # @return [Starling::Services::MerchantsService] a configured service for accessing
+    #                                                the Merchants API
+    def merchants
+      Services::MerchantsService.new(@api_service)
+    end
+
+    # Provides access to the Merchants Locations API
+    #
+    # @return [Starling::Services::MerchantLocationsService] a configured service for
+    #                                                        accessing the Merchant
+    #                                                        Locations API
+    def merchant_locations
+      Services::MerchantLocationsService.new(@api_service)
+    end
+
+    # Provides access to the Card API
+    #
+    # @return [Starling::Services::CardService] a configured service for accessing the
+    #                                           Card API
+    def card
+      Services::CardService.new(@api_service)
+    end
+
+    # Provides access to the Who Am I (Me) API
+    #
+    # @return [Starling::Services::MeService] a configured service for accessing the Who
+    #                                         Am I (Me) API
+    def me
+      Services::MeService.new(@api_service)
+    end
+
+    # Provides access to the Customer API
+    #
+    # @return [Starling::Services::CustomerService] a configured service for accessing
+    #                                               the Customer API
+    def customer
+      Services::CustomerService.new(@api_service)
+    end
+
+    # Provides access to the Addresses API
+    #
+    # @return [Starling::Services::AddressesService] a configured service for accessing
+    #                                                the Addresses API
+    def addresses
+      Services::AddressesService.new(@api_service)
+    end
+
+    # Provides access to the Direct Debit Mandates API
+    #
+    # @return [Starling::Services::DirectDebitMandatesService] a configured service for
+    #                                                          accessing the Direct Debit
+    #                                                          Mandates API
+    def direct_debit_mandates
+      Services::DirectDebitMandatesService.new(@api_service)
+    end
+
+    # Provides access to the Contacts API
+    #
+    # @return [Starling::Services::ContactsService] a configured service for accessing
+    #                                               the Contacts API
+    def contacts
+      Services::ContactsService.new(@api_service)
+    end
+
+    # Provides access to the Contact Accounts API
+    #
+    # @return [Starling::Services::ContactAccountsService] a configured service for
+    #                                                      accessing the Contact Accounts
+    #                                                      API
+    def contact_accounts
+      Services::ContactAccountsService.new(@api_service)
+    end
+
+    # Provides access to the Transaction Faster Payment In API
+    #
+    # @return [Starling::Services::InboundFasterPaymentsTransactionsService] a configured
+    #                                                                        service for
+    #                                                                        accessing
+    #                                                                        the
+    #                                                                        Transaction
+    #                                                                        Faster
+    #                                                                        Payment In
+    #                                                                        API
+    def inbound_faster_payments_transactions
+      Services::InboundFasterPaymentsTransactionsService.new(@api_service)
+    end
+
+    # Provides access to the Transaction Faster Payment Out API
+    #
+    # @return [Starling::Services::OutboundFasterPaymentsTransactionsService] a
+    #                                                                         configured
+    #                                                                         service for
+    #                                                                         accessing
+    #                                                                         the
+    #                                                                         Transaction
+    #                                                                         Faster
+    #                                                                         Payment Out
+    #                                                                         API
+    def outbound_faster_payments_transactions
+      Services::OutboundFasterPaymentsTransactionsService.new(@api_service)
+    end
+
+    # Provides access to the Transaction Direct Debit API
+    #
+    # @return [Starling::Services::DirectDebitTransactionsService] a configured service
+    #                                                              for accessing the
+    #                                                              Transaction Direct
+    #                                                              Debit API
+    def direct_debit_transactions
+      Services::DirectDebitTransactionsService.new(@api_service)
+    end
+
+    # Provides access to the Payment API
+    #
+    # @return [Starling::Services::PaymentsService] a configured service for accessing
+    #                                               the Payment API
+    def payments
+      Services::PaymentsService.new(@api_service)
+    end
+
+    # Provides access to the Transaction Mastercard API
+    #
+    # @return [Starling::Services::MastercardTransactionsService] a configured service
+    #                                                             for accessing the
+    #                                                             Transaction Mastercard
+    #                                                             API
+    def mastercard_transactions
+      Services::MastercardTransactionsService.new(@api_service)
+    end
+
     private
 
     def fetch_base_url_for_environment(environment)

data/lib/starling/errors/api_error.rb

@@ -2,13 +2,46 @@ require 'json'
 
 module Starling
   module Errors
+    # An error raised when the Starling Bank API responds in a way indicating an error
     class ApiError < BaseError
+      # @return [String] a helpful message explaining the error, incorporating the
+      #                  HTTP status code and the error message (either parsed from the
+      #                  JSON for a JSON response, or the whole body)
       def message
-        return super unless json?
-        return super if error.nil? || error_description.nil?
+        # If there response isn't JSON or either the Starling-provided error or error
+        # description is missing, return a simpler error from BaseError
+        return super unless error && error_description
 
         "#{status}: #{error_description} (#{error})"
       end
+      alias to_s message
+
+      # @return [String] the error name returned by the Starling Bank API
+      def error
+        return unless json?
+        parsed_body['error']
+      end
+
+      # @return [String] the error description returned by the Starling Bank API
+      def error_description
+        return unless json?
+        parsed_body['error_description']
+      end
+
+      # @return [Hash] the parsed JSON response, if there is a valid JSON body
+      # @return [nil] if there is no body, or the body is not valid JSON
+      def parsed_body
+        return unless body
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      private
+
+      def json?
+        parsed_body
+      end
     end
   end
 end

data/lib/starling/errors/base_error.rb

@@ -2,9 +2,13 @@ require 'json'
 
 module Starling
   module Errors
+    # A basic implementation of an error thrown from a {Faraday::Response::Middleware},
+    # receiving the Faraday environment as an argument, providing access to the response
+    # status and body
     class BaseError < StandardError
       extend Forwardable
 
+      # @param env The Faraday environment, providing access to the response
       def initialize(env)
         @env = env
       end
@@ -12,37 +16,15 @@ module Starling
       def_delegator :@env, :status
       def_delegator :@env, :body
 
+      # @return [String] a helpful message explaining the error, incorporating the
+      #                  HTTP status code and body returned
       def message
         message = status.to_s
         message += ": #{body}" if body
 
         message
       end
-
       alias to_s message
-
-      def error
-        return unless json?
-        parsed_body['error']
-      end
-
-      def error_description
-        return unless json?
-        parsed_body['error_description']
-      end
-
-      def parsed_body
-        return if body.nil?
-        JSON.parse(body)
-      rescue JSON::ParserError
-        nil
-      end
-
-      private
-
-      def json?
-        !parsed_body.nil?
-      end
     end
   end
 end

data/lib/starling/middlewares/raise_starling_errors.rb

@@ -1,21 +1,22 @@
 module Starling
   module Middlewares
+    # A Faradfay::Response::Middleware used to raise an {{Errors::ApiError}} when the
+    # Starling Bank API responds with an HTTP status code indicating an error. The raised
+    # error provides access to the response.
     class RaiseStarlingErrors < Faraday::Response::Middleware
+      # HTTP status codes which are considered to be an error (alongside non-JSON)
+      # responses
       ERROR_STATUSES = 400..599
 
+      # @param env The Faraday environment, providing access to the response
+      # @raise [Errors::ApiError] if the response from the Starling Bank API indicates an
+      #                           error
+      # @return [nil] if the response from the Starling Bank API doesn't indicate an
+      #               error
       def on_complete(env)
-        return unless !json?(env) || ERROR_STATUSES.include?(env.status)
+        return unless ERROR_STATUSES.include?(env.status)
         raise Errors::ApiError, env
       end
-
-      private
-
-      def json?(env)
-        content_type = env.response_headers['Content-Type'] ||
-                       env.response_headers['content-type'] || ''
-
-        content_type.include?('application/json')
-      end
     end
   end
 end

data/lib/starling/request.rb

@@ -1,19 +1,31 @@
 module Starling
+  # The interface between Starling and Faraday, which is used under the hood to make
+  # HTTP requests
   class Request
-    def initialize(connection, method, path, options)
+    # @param connection [Faraday] A Faraday connection
+    # @param method [Symbol] The HTTP method for the request
+    # @param path [String] The path of the API endpoint, which will be added to the
+    #                      base URL (from {Starling::Client::ENVIRONMENT_BASE_URLS}) and
+    #                      the API version-specific base path ({ApiService::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] The headers to be included in the request
+    def initialize(connection, method, path, params: {}, headers: {})
       @connection = connection
       @method = method
       @path = path
-      @headers = options.delete(:headers) || {}
-      @options = options
-      @request_body = request_body
-      @request_query = request_query
+      @headers = headers
+      @request_body = params if %i[post put delete].include?(method)
+      @request_query = method == :get ? params : {}
 
       return unless @request_body.is_a?(Hash)
       @request_body = @request_body.to_json
       @headers['Content-Type'] ||= 'application/json'
     end
 
+    # Dispatch the configured HTTP request
+    #
+    # @return [Faraday::Request] The response from the HTTP request
     def make_request
       @connection.send(@method) do |request|
         request.url @path
@@ -22,19 +34,5 @@ module Starling
         request.headers.merge!(@headers)
       end
     end
-
-    private
-
-    def request_body
-      return @options.fetch(:params, {}) if %i[post put delete].include?(@method)
-
-      nil
-    end
-
-    def request_query
-      return @options.fetch(:params, {}) if @method == :get
-
-      {}
-    end
   end
 end

data/lib/starling/resources/account_balance_resource.rb

@@ -1,32 +1,40 @@
 module Starling
   module Resources
+    # A resource representing a response from the Account Balance API
     class AccountBalanceResource < BaseResource
+      # @return [Float] the account's accepted overdraft
       def accepted_overdraft
-        parsed_data['acceptedOverdraft']
+        present_float(parsed_data['acceptedOverdraft'])
       end
 
+      # @return [Float] the account's balance
       def amount
-        parsed_data['amount']
+        present_float(parsed_data['amount'])
       end
 
+      # @return [Float] the account's amount available to spend
       def available_to_spend
-        parsed_data['availableToSpend']
+        present_float(parsed_data['availableToSpend'])
       end
 
+      # @return [Float] the account's cleared balance
       def cleared_balance
-        parsed_data['clearedBalance']
+        present_float(parsed_data['clearedBalance'])
       end
 
+      # @return [String] the account's currency (e.g. "GBP")
       def currency
         parsed_data['currency']
       end
 
+      # @return [Float] the account's effective balance
       def effective_balance
-        parsed_data['effectiveBalance']
+        present_float(parsed_data['effectiveBalance'])
       end
 
+      # @return [Float] the total of the account's pending transactions
       def pending_transactions
-        parsed_data['pendingTransactions']
+        present_float(parsed_data['pendingTransactions'])
       end
     end
   end

data/lib/starling/resources/account_resource.rb

@@ -1,34 +1,44 @@
 module Starling
   module Resources
+    # A resource representing a response from the Account API
     class AccountResource < BaseResource
+      # @return [Time] the time and date when the account was created
       def created_at
         present_datetime(parsed_data['createdAt'])
       end
 
+      # @return [String] the currency of the account
       def currency
         parsed_data['currency']
       end
 
+      # @return [String] the IBAN of the account
       def iban
         parsed_data['iban']
       end
 
+      # @return [String] the BIC of the account
       def bic
         parsed_data['bic']
       end
 
+      # @return [String] the Starling internal ID of the account
       def id
         parsed_data['id']
       end
 
+      # @return [String] the name of the account
       def name
         parsed_data['name']
       end
 
+      # @return [String] the account number of the account
       def number
         parsed_data['number']
       end
+      alias account_number number
 
+      # @return [String] the sort code of the account
       def sort_code
         parsed_data['sortCode']
       end