starling-ruby 0.1.0 → 0.2.0

data/lib/starling/resources/me_resource.rb

@@ -0,0 +1,26 @@
+module Starling
+  module Resources
+    # A resource representing a response returned from the Who Am I (Me) API
+    class MeResource < BaseResource
+      # @return [String] the Starling internal ID of the user
+      def customer_uid
+        parsed_data['customerUid']
+      end
+
+      # @return [true, false] whether the user is authenticated
+      def authenticated
+        parsed_data['authenticated']
+      end
+
+      # @return [Integer, Fixnum] the time until the user's access token expires
+      def expires_in_seconds
+        parsed_data['expiresInSeconds']
+      end
+
+      # @return [Array<String>] the scopes of the user's access token
+      def scopes
+        parsed_data['scopes']
+      end
+    end
+  end
+end

data/lib/starling/resources/merchant_location_resource.rb

@@ -0,0 +1,33 @@
+module Starling
+  module Resources
+    # A resource representing a Merchant Location returned from the Merchant Locations API
+    class MerchantLocationResource < BaseResource
+      # @return [String] the Starling internal ID of the merchant
+      def merchant_uid
+        parsed_data['merchantUid']
+      end
+
+      # @return [String] the Starling internal ID of the merchant location
+      def merchant_location_uid
+        parsed_data['merchantLocationUid']
+      end
+
+      # @return [String] the name of the merchant
+      def merchant_name
+        parsed_data['merchantName']
+      end
+
+      # @return [String] the name of the merchant location
+      def location_name
+        parsed_data['locationName']
+      end
+
+      # @return [Integer, Fixnum] the MasterCard merchant category code - see
+      #                           {https://www.mastercard.us/content/dam/mccom/en-us/docments/rules/quick-reference-booklet-me-nov_2015.pdf here}
+      #                           for details
+      def mastercard_merchant_category_code
+        parsed_data['mastercardMerchantCategoryCode']
+      end
+    end
+  end
+end

data/lib/starling/resources/merchant_resource.rb

@@ -0,0 +1,34 @@
+module Starling
+  module Resources
+    # A resource representing a Merchant returned from the Merchants API
+    class MerchantResource < BaseResource
+      # @return [String] the Starling internal ID of the merchant
+      def merchant_uid
+        parsed_data['merchantUid']
+      end
+
+      # @return [String] the name of the merchant
+      def name
+        parsed_data['name']
+      end
+
+      # @return [String, nil] the website address of the merchant, or nil if this is not
+      #                       known
+      def website
+        parsed_data['website']
+      end
+
+      # @return [String, nil] the phone number of the merchant, or nil if this is not
+      #                       known
+      def phone_number
+        parsed_data['phoneNumber']
+      end
+
+      # @return [String, nil] the Twitter username of the merchant, prefixed with "@", or
+      #                       nil if this is not known
+      def twitter_username
+        parsed_data['twitterUsername']
+      end
+    end
+  end
+end

data/lib/starling/resources/outbound_faster_payments_transaction_resource.rb

@@ -0,0 +1,56 @@
+module Starling
+  module Resources
+    # A resource representing a Transaction returned from the Transactions Faster
+    # Payments Out API
+    class OutboundFasterPaymentsTransactionResource < BaseResource
+      # @return [String] the Starling internal ID of the transaction
+      def id
+        parsed_data['id']
+      end
+
+      # @return [String] the currency of the transaction (e.g. "GBP" or "UAH")
+      def currency
+        parsed_data['currency']
+      end
+
+      # @return [Float] the amount of the transaction
+      def amount
+        present_float(parsed_data['amount'])
+      end
+
+      # @return [Symbol] the direction of the transaction (e.g. `:outbound`)
+      def direction
+        present_enum(parsed_data['direction'])
+      end
+
+      # @return [Time] the date and time when the transaction was recorded
+      def created
+        present_datetime(parsed_data['created'])
+      end
+      alias created_at created
+
+      # @return [String] the narrative of the transaction
+      def narrative
+        parsed_data['narrative']
+      end
+
+      # @return [Symbol] the source of the transaction (e.g. `:master_card`)
+      def source
+        present_enum(parsed_data['source'])
+      end
+
+      # @return [String, nil] the Starling internal ID of the contact who the payment was
+      #                       sent to, or nil if they are not one of the user's contacts
+      def receiving_contact_id
+        parsed_data['receivingContactId']
+      end
+
+      # @return [String, nil] the Starling internal ID of the contact account the payment
+      #                       was sent to, or nil if they are not one of the user's
+      #                       contacts
+      def receiving_contact_account_id
+        parsed_data['receivingContactAccountId']
+      end
+    end
+  end
+end

data/lib/starling/resources/payment_resource.rb

@@ -0,0 +1,78 @@
+module Starling
+  module Resources
+    # A resource representing a Payment returned from the Payment API
+    class PaymentResource < BaseResource
+      # @return [String] the Starling internal ID of the payment
+      def payment_order_id
+        parsed_data['paymentOrderId']
+      end
+      alias id payment_order_id
+
+      # @return [String] the currency of the payment
+      def currency
+        parsed_data['currency']
+      end
+
+      # @return [Float] the amount of the payment
+      def amount
+        present_float(parsed_data['amount'])
+      end
+
+      # @return [String] the reference of the payment
+      def reference
+        parsed_data['reference']
+      end
+
+      # @return [String] the Starling internal ID of the contact account the payment
+      #                  is/was sent to
+      def receiving_contact_account_id
+        parsed_data['receivingContactAccountId']
+      end
+
+      # @return [String] the name of the recipient of the payment
+      def recipient_name
+        parsed_data['recipientName']
+      end
+
+      # @return [true, false] where the payment is immediate or scheduled for the future
+      def immediate
+        parsed_data['immediate']
+      end
+
+      # Returns a Hash describing the recurrence behaviour of the payment, or nil if the
+      # payment is not recurring. The values in the Hash will be parsed directly from
+      # JSON (e.g. dates will appear as strings).
+      #
+      # TODO: Consider replacing this with its own resource
+      #
+      # @return [Hash, nil] a Hash describing the recurrence behaviour of the payment,
+      #                     with values parsed directly from JSON, or nil if the payment
+      #                     is not recurring
+      def recurrence_rule
+        parsed_data['recurrenceRule']
+      end
+
+      # @return [Date] the start date of the payment
+      def start_date
+        present_date(parsed_data['startDate'])
+      end
+
+      # @return [Date] the date of the next payment in the series
+      def next_date
+        present_date(parsed_data['nextDate'])
+      end
+
+      # @return [Time, nil] the time when the payment was cancelled, or nil if it has not
+      #                     been cancelled
+      def cancelled_at
+        present_datetime(parsed_data['cancelledAt'])
+      end
+
+      # @return [Symbol] the type of the payment (e.g. `:standing_order`) (these values
+      #                  do not seem to be accurate!)
+      def payment_type
+        present_enum(parsed_data['paymentType'])
+      end
+    end
+  end
+end

data/lib/starling/resources/transaction_resource.rb

@@ -0,0 +1,42 @@
+module Starling
+  module Resources
+    # A resource representing a Transaction returned from the Transactions API
+    class TransactionResource < BaseResource
+      # @return [String] the Starling internal ID of the transaction
+      def id
+        parsed_data['id']
+      end
+
+      # @return [String] the currency of the transaction (e.g. "GBP" or "UAH")
+      def currency
+        parsed_data['currency']
+      end
+
+      # @return [Float] the amount of the transaction
+      def amount
+        present_float(parsed_data['amount'])
+      end
+
+      # @return [Symbol] the direction of the transaction (e.g. `:outbound`)
+      def direction
+        present_enum(parsed_data['direction'])
+      end
+
+      # @return [Time] the date and time when the transaction was recorded
+      def created
+        present_datetime(parsed_data['created'])
+      end
+      alias created_at created
+
+      # @return [String] the narrative of the transaction
+      def narrative
+        parsed_data['narrative']
+      end
+
+      # @return [Symbol] the source of the transaction (e.g. `:master_card`)
+      def source
+        present_enum(parsed_data['source'])
+      end
+    end
+  end
+end

data/lib/starling/services/account_balance_service.rb

@@ -1,8 +1,17 @@
 module Starling
   module Services
+    # A service for accessing the Account API's Get Balance endpoint
     class AccountBalanceService < BaseService
-      def get(options = {})
-        response = @api_service.make_request(:get, '/accounts/balance', options)
+      # @param params [Hash] Parameters which will be included in the HTTP request,
+      #                      included in the URL as a query string
+      # @param headers [Hash] Headers which be included in the HTTP request, merged on
+      #                       top of the headers set at the {Client} level
+      # @return [Resources::AccountBalanceResource]
+      # @raise [Errors::ApiError] if the HTTP request returns a status indicating that it
+      #                           was unsuccessful
+      def get(params: {}, headers: {})
+        response = api_service.make_request(:get, '/accounts/balance', params: params,
+                                                                       headers: headers)
         resource.new(response: response)
       end
 

data/lib/starling/services/account_service.rb

@@ -1,12 +1,25 @@
 module Starling
   module Services
+    # A service for accessing the Account API's Get Account endpoint
     class AccountService < BaseService
-      def get(options = {})
-        resource.new(response: @api_service.make_request(:get, '/accounts', options))
+      # @param params [Hash] Parameters which will be included in the HTTP request,
+      #                      included in the URL as a query string
+      # @param headers [Hash] Headers which be included in the HTTP request, merged on
+      #                       top of the headers set at the {Client} level
+      # @return [Resources::AccountResource]
+      # @raise [Errors::ApiError] if the HTTP request returns a status indicating that it
+      #                           was unsuccessful
+      def get(params: {}, headers: {})
+        response = api_service.make_request(:get, '/accounts', params: params,
+                                                               headers: headers)
+
+        resource.new(response: response)
       end
 
+      # @return [Services::AccountBalanceService] a configured service for accessing the
+      #                                           Account Balance API
       def balance
-        Services::AccountBalanceService.new(@api_service)
+        Services::AccountBalanceService.new(api_service)
       end
 
       private

data/lib/starling/services/addresses_service.rb

@@ -0,0 +1,26 @@
+module Starling
+  module Services
+    # A service for accessing the Address API
+    class AddressesService < BaseService
+      # @param params [Hash] Parameters which will be included in the HTTP request,
+      #                      included in the URL as a query string
+      # @param headers [Hash] Headers which be included in the HTTP request, merged on
+      #                       top of the headers set at the {Client} level
+      # @return [Resources::AddressesResource]
+      # @raise [Errors::ApiError] if the HTTP request returns a status indicating that it
+      #                           was unsuccessful
+      def get(params: {}, headers: {})
+        response = api_service.make_request(:get, '/addresses', params: params,
+                                                                headers: headers)
+
+        resource.new(response: response)
+      end
+
+      private
+
+      def resource
+        Resources::AddressesResource
+      end
+    end
+  end
+end

data/lib/starling/services/base_service.rb

@@ -2,20 +2,41 @@ require 'json'
 
 module Starling
   module Services
+    # A basic implementation of a service for interacting with the
+    # Starling Bank API, mapping HTTP request to endpoints to Ruby methods
     class BaseService
+      # @param api_service [ApiService]
       def initialize(api_service)
         @api_service = api_service
       end
 
       private
 
-      def build_collection(response, key:, resource:)
+      attr_reader :api_service
+
+      def build_collection_from_key(response, key:, resource:)
+        JSON.parse(response.body)
+            .fetch(key)
+            .map do |parsed_data|
+          resource.new(parsed_data: parsed_data)
+        end
+      end
+
+      def build_collection_from_embedded_key(response, key:, resource:)
         JSON.parse(response.body)
             .fetch('_embedded', {})
             .fetch(key, []).map do |parsed_data|
           resource.new(parsed_data: parsed_data)
         end
       end
+
+      def options_without_params(options)
+        options.reject { |key, _| key == :params }
+      end
+
+      def convert_location_header_to_relative_path(location)
+        location.gsub(%r{^/api/v1}, '')
+      end
     end
   end
 end

data/lib/starling/services/card_service.rb

@@ -0,0 +1,26 @@
+module Starling
+  module Services
+    # A service for accessing the Card API
+    class CardService < BaseService
+      # @param params [Hash] Parameters which will be included in the HTTP request,
+      #                      included in the URL as a query string
+      # @param headers [Hash] Headers which be included in the HTTP request, merged on
+      #                       top of the headers set at the {Client} level
+      # @return [Resources::CardResource]
+      # @raise [Errors::ApiError] if the HTTP request returns a status indicating that it
+      #                           was unsuccessful
+      def get(params: {}, headers: {})
+        response = api_service.make_request(:get, '/cards', params: params,
+                                                            headers: headers)
+
+        resource.new(response: response)
+      end
+
+      private
+
+      def resource
+        Resources::CardResource
+      end
+    end
+  end
+end

data/lib/starling/services/contact_accounts_service.rb

@@ -0,0 +1,54 @@
+module Starling
+  module Services
+    # A service for accessing the Contact API's Get Contact Accounts and Get Contact
+    # endpoints
+    class ContactAccountsService < BaseService
+      # @param contact_id [String] The Starling internal ID of the contact the contact
+      #                            account belongs to
+      # @param contact_account_id [String] The Starling internal ID of the contact
+      #                                     account
+      # @param params [Hash] Parameters which will be included in the HTTP request,
+      #                      included in the URL as a query string
+      # @param headers [Hash] Headers which be included in the HTTP request, merged on
+      #                       top of the headers set at the {Client} level
+      # @return [Resources::ContactAccountResource]
+      # @raise [Errors::ApiError] if the HTTP request returns a status indicating that it
+      #                           was unsuccessful
+      def get(contact_id, contact_account_id, params: {}, headers: {})
+        response = api_service.make_request(
+          :get,
+          "/contacts/#{contact_id}/accounts/#{contact_account_id}",
+          params: params,
+          headers: headers
+        )
+
+        resource.new(response: response)
+      end
+
+      # @param contact_id [String] The Starling internal ID of the contact
+      # @param params [Hash] Parameters which will be included in the HTTP request,
+      #                      included in the URL as a query string
+      # @param headers [Hash] Headers which be included in the HTTP request, merged on
+      #                       top of the headers set at the {Client} level
+      # @return [Array<Resources::ContactAccountResource>]
+      # @raise [Errors::ApiError] if the HTTP request returns a status indicating that it
+      #                           was unsuccessful
+      def list(contact_id, params: {}, headers: {})
+        response = api_service.make_request(
+          :get,
+          "/contacts/#{contact_id}/accounts",
+          params: params,
+          headers: headers
+        )
+
+        build_collection_from_key(response, key: 'contactAccounts', resource: resource)
+      end
+
+      private
+
+      def resource
+        Resources::ContactAccountResource
+      end
+    end
+  end
+end