k2-connect-ruby 3.1.0 → 4.0.0

data/k2-connect-ruby.gemspec

@@ -1,54 +1,58 @@
-lib = File.expand_path('lib', __dir__)
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'k2-connect-ruby/version'
+require "k2-connect-ruby/version"
 
 Gem::Specification.new do |spec|
-  spec.name                  = 'k2-connect-ruby'
+  spec.name                  = "k2-connect-ruby"
   spec.version               = K2ConnectRuby::VERSION
-  spec.authors               = ['DavidKar1uk1']
-  spec.email                 = ['David.mwangi@kopokopo.com']
+  spec.authors               = ["DavidKar1uk1"]
+  spec.email                 = ["David.mwangi@kopokopo.com"]
 
-  spec.summary               = 'Ruby SDK for the Kopo Kopo K2 Connect API.'
-  spec.description           = 'Ruby SDK for the Kopo Kopo K2 Connect API, with webhook subscriptions, STK Push, Pay and Settlement Transfer capabilities. Allows decomposition and break down of results and webhooks returned from the K2 Connect APIx``.'
-  spec.homepage              = 'https://github.com/kopokopo/k2-connect-ruby.git'
-  spec.license               = 'MIT'
-  spec.required_ruby_version = ['>= 3.3.5', '<= 3.4.7']
+  spec.summary               = "Ruby SDK for the Kopo Kopo K2 Connect API."
+  spec.description           = "Ruby SDK for the Kopo Kopo K2 Connect API, with webhook subscriptions, STK Push and Send Money capabilities. Allows decomposition and break down of results and webhooks returned from the K2 Connect API."
+  spec.homepage              = "https://github.com/kopokopo/k2-connect-ruby.git"
+  spec.license               = "MIT"
+  spec.required_ruby_version = [">= 3.3.5", "<= 3.4.7"]
 
 
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the "allowed_push_host"
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
-    spec.metadata['homepage_uri'] = spec.homepage
-    spec.metadata['source_code_uri'] = 'https://github.com/kopokopo/k2-connect-ruby.git'
-    spec.metadata['changelog_uri'] = 'https://github.com/kopokopo/k2-connect-ruby.git/CHANGELOG.MD'
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/kopokopo/k2-connect-ruby.git"
+    spec.metadata["changelog_uri"] = "https://github.com/kopokopo/k2-connect-ruby.git/CHANGELOG.MD"
   else
-    raise 'RubyGems 2.0 or newer is required to protect against ' \
-      'public gem pushes.'
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
   end
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    %x(git ls-files -z).split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = 'exe'
+  spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-
-
-  spec.add_dependency 'activesupport', ['>= 7.2.2', '< 8.1.1']
-  spec.add_dependency 'activemodel', ['>= 7.2.2', '< 8.1.1']
-  spec.add_dependency 'rest-client', '~> 2.1.0'
-  spec.add_dependency 'json', '~> 2.8.2'
-  spec.add_development_dependency 'bundler', '~> 2.5.16'
-  spec.add_development_dependency "guard", '~> 2.19'
-  spec.add_development_dependency "guard-rspec", '~> 4.7.3'
-  spec.add_development_dependency 'rake', '~> 13.2.1'
-  spec.add_development_dependency 'rspec', '~> 3.13.0'
-  spec.add_development_dependency "rspec-nc", '~> 0.3.0'
-  spec.add_development_dependency 'vcr', '~> 6.3.1'
-  spec.add_development_dependency 'webmock', '~> 3.24'
-  spec.add_development_dependency 'faker', '~> 3.5.1'
+  spec.require_paths = ["lib"]
+
+
+  spec.add_dependency("activemodel", [">= 7.2.2", "<= 8.1.1"])
+  spec.add_dependency("activesupport", [">= 7.2.2", "<= 8.1.1"])
+  spec.add_dependency("json", "~> 2.8.2")
+  spec.add_dependency("rest-client", "~> 2.1.0")
+  spec.add_development_dependency("bundler", "~> 4.0.3")
+  spec.add_development_dependency("faker", "~> 3.5.1")
+  spec.add_development_dependency("guard", "~> 2.19")
+  spec.add_development_dependency("guard-rspec", "~> 4.7.3")
+  spec.add_development_dependency("rake", "~> 13.2.1")
+  spec.add_development_dependency("rspec", "~> 3.13.0")
+  spec.add_development_dependency("rspec-nc", "~> 0.3.0")
+  spec.add_development_dependency("rubocop", "~> 1.80.1")
+  spec.add_development_dependency("rubocop-shopify", "~> 2.17.1")
+  spec.add_development_dependency("vcr", "~> 6.3.1")
+  spec.add_development_dependency("webmock", "~> 3.24")
 end

data/lib/k2-connect-ruby/entity.rb

@@ -1,12 +1,42 @@
-require 'k2-connect-ruby/k2_entity/k2_entity'
-require 'k2-connect-ruby/k2_entity/k2_token'
-require 'k2-connect-ruby/k2_entity/k2_polling'
-require 'k2-connect-ruby/k2_entity/k2_subscribe'
-require 'k2-connect-ruby/k2_entity/k2_notification'
-require 'k2-connect-ruby/k2_entity/k2_financial_entities/k2_stk'
-require 'k2-connect-ruby/k2_entity/k2_financial_entities/k2_pay'
-require 'k2-connect-ruby/k2_entity/k2_financial_entities/k2_transfer'
-require 'k2-connect-ruby/k2_entity/k2_financial_entities/k2_settlement'
+require "k2-connect-ruby/k2_entity/k2_entity"
+require "k2-connect-ruby/k2_entity/k2_token"
+
+require "k2-connect-ruby/k2_entity/k2_polling"
+require "k2-connect-ruby/k2_entity/polling/polling_request"
+
+require "k2-connect-ruby/k2_entity/k2_subscribe"
+require "k2-connect-ruby/k2_entity/webhook/webhook_subscription_request"
+
+require "k2-connect-ruby/k2_entity/k2_financial_entities/k2_stk"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/stk_push/stk_push_request"
+
+require "k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/recipient_request"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/till"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/paybill"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/bank_account"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/mobile_wallet"
+
+require "k2-connect-ruby/k2_entity/k2_financial_entities/send_money"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/send_money/send_money_request"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/destination/destination_request"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_till"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_paybill"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_bank_account"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_mpesa_wallet"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/destination/merchant_bank_account"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/destination/merchant_mpesa_wallet"
+
+require "k2-connect-ruby/k2_entity/k2_financial_entities/transfer_account"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/transfer_account/transfer_account_request"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/transfer_account/merchant_bank_account"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/transfer_account/merchant_mpesa_wallet"
+
+require "k2-connect-ruby/k2_entity/k2_financial_entities/reversal"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/reversals/reversal_request"
+
+require "k2-connect-ruby/k2_entity/k2_financial_entities/payment_link"
+require "k2-connect-ruby/k2_entity/k2_financial_entities/payment_links/payment_link_request"
 
 module K2ConnectRuby
   module Entity; end

data/lib/k2-connect-ruby/http_client.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module K2ConnectRuby
+  class HttpClient
+    class << self
+      def post(url, payload:, headers:)
+        request { RestClient.post(url, payload, headers) }
+      end
+
+      def get(url, headers:)
+        request { RestClient.get(url, headers) }
+      end
+
+      private
+
+      def request
+        yield
+      rescue RestClient::Unauthorized
+        raise K2ConnectRuby::K2Errors::UnauthorizedError, "Invalid or expired token"
+      rescue RestClient::RequestTimeout
+        raise K2ConnectRuby::K2Errors::TimeoutError, "Request timed out"
+      rescue RestClient::NotFound
+        raise K2ConnectRuby::K2Errors::NotFoundError, "Entity not found"
+      rescue Errno::ECONNREFUSED
+        raise K2ConnectRuby::K2Errors::ConnectionError, "Connection refused"
+      rescue RestClient::Exception => e
+        body = parse_body(e)
+
+        raise K2ConnectRuby::K2Errors::ApiError.new(
+          message: body&.dig("error_message") || body&.dig("error_description") || "API error",
+          code: e.http_code,
+          details: body,
+        )
+      end
+
+      def parse_body(exception)
+        JSON.parse(exception.response.body)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_entity.rb

@@ -1,31 +1,32 @@
+# frozen_string_literal: true
+
 # Common Class Behaviours for stk, pay and transfers
 module K2ConnectRuby
   module K2Entity
     class K2Entity
-      attr_accessor :access_token, :the_array
+      attr_accessor :access_token
       attr_reader :k2_response_body, :query_hash, :location_url
-      include K2ConnectRuby::K2Utilities::K2Validation, K2ConnectRuby::K2Utilities
+
+      include K2ConnectRuby::K2Utilities
 
       # Initialize with access token from Subscriber Class
       def initialize(access_token)
         @access_token = access_token
-        @exception_array = %w[authenticity_token]
       end
 
       # Query/Check the status of a previously initiated request
-      def query_status(class_type, path_url)
-        query(class_type, path_url)
+      def query_status(endpoint)
+        query(endpoint)
       end
 
       # Query Location URL
-      def query_resource(class_type, url)
-        query(class_type, url)
+      def query_resource(endpoint)
+        query(endpoint)
       end
 
-      def query(class_type, path_url)
-        path_url = validate_url(path_url)
-        query_hash = make_hash(path_url, 'get', @access_token, class_type, nil)
-        @k2_response_body = K2ConnectRuby::K2Utilities::K2Connection.make_request(query_hash)
+      def query(endpoint)
+        result = K2ConnectRuby::K2Services::SendK2ConnectGetRequestService.call(access_token, endpoint)
+        @k2_response_body = result.data[:response_body]
       end
     end
   end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/destination/destination_request.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module Destination
+        class DestinationRequest
+          include ActiveModel::Validations
+
+          attr_accessor :type, :nickname, :amount, :description, :favourite
+
+          validates :type, :amount, presence: true
+          validates :favourite, inclusion: { in: [true, false, 'true', 'false', 1, 0, 'T', 'F'],
+                                             message: 'is not a valid boolean' }, if: -> { favourite.present? }
+
+          def initialize(kwargs)
+            kwargs.each do |key, value|
+              instance_variable_set("@#{key}", value)
+            end
+          end
+
+          def destination_payload; end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_bank_account.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Class for collecting destination details for external bank accounts
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module Destination
+        class ExternalBankAccount < DestinationRequest
+          include ActiveModel::Validations
+
+          attr_accessor :account_name, :account_number, :bank_branch_ref
+
+          validates :account_name, :account_number, :bank_branch_ref, :description, presence: true
+
+          def destination_payload
+            {
+              type: type,
+              nickname: nickname,
+              account_name: account_name,
+              account_number: account_number,
+              bank_branch_ref: bank_branch_ref,
+              amount: amount,
+              description: description,
+              favourite: ActiveModel::Type::Boolean.new.cast(favourite)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_mpesa_wallet.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Class for collecting destination details for external M-PESA numbers
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module Destination
+        class ExternalMpesaWallet < DestinationRequest
+          include ActiveModel::Validations
+
+          attr_accessor :phone_number, :network
+
+          validates :phone_number, :description, presence: true
+          validate :phone_number_format
+
+          def destination_payload
+            {
+              type: type,
+              nickname: nickname,
+              phone_number: phone_number,
+              network: network,
+              amount: amount,
+              description: description,
+              favourite: ActiveModel::Type::Boolean.new.cast(favourite),
+            }
+          end
+
+          def phone_number_format
+            unless phone_number&.match?(/^(254\d{9})$/)
+              errors.add(:phone_number, "#{phone_number} has an invalid length or format. Must be 254XXXXXXXXX.")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_paybill.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Class for collecting destination details for external paybills
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module Destination
+        class ExternalPaybill < DestinationRequest
+          include ActiveModel::Validations
+
+          attr_accessor :paybill_number, :paybill_account_number
+
+          validates :paybill_number, :paybill_account_number, :description, presence: true
+
+          def destination_payload
+            {
+              type: type,
+              nickname: nickname,
+              paybill_number: paybill_number,
+              paybill_account_number: paybill_account_number,
+              amount: amount,
+              description: description,
+              favourite: ActiveModel::Type::Boolean.new.cast(favourite)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/destination/external_till.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Class for collecting destination details for external till
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module Destination
+        class ExternalTill < DestinationRequest
+          include ActiveModel::Validations
+
+          attr_accessor :till_number
+
+          validates :till_number, :description, presence: true
+
+          def destination_payload
+            {
+              type: type,
+              nickname: nickname,
+              till_number: till_number,
+              amount: amount,
+              description: description,
+              favourite: ActiveModel::Type::Boolean.new.cast(favourite)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/destination/merchant_bank_account.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Class for collecting destination details for my bank account
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module Destination
+        class MerchantBankAccount < DestinationRequest
+          include ActiveModel::Validations
+
+          attr_accessor :reference
+
+          validates :reference, presence: true
+
+          def destination_payload
+            {
+              type: type,
+              reference: reference,
+              amount: amount,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/destination/merchant_mpesa_wallet.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Class for collecting destination details for my M-PESA phone
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module Destination
+        class MerchantMpesaWallet < DestinationRequest
+          include ActiveModel::Validations
+
+          attr_accessor :reference
+
+          validates :reference, presence: true
+
+          def destination_payload
+            {
+              type: type,
+              reference: reference,
+              amount: amount,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/bank_account.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module ExternalRecipient
+        class BankAccount < RecipientRequest
+          include ActiveModel::Validations
+
+          attr_accessor :account_name, :account_number, :bank_branch_ref
+
+          validates :account_name, :account_number, :bank_branch_ref, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/mobile_wallet.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module ExternalRecipient
+        class MobileWallet < RecipientRequest
+          include ActiveModel::Validations
+
+          attr_accessor :first_name, :last_name, :phone_number, :email, :network
+
+          validates :first_name, :last_name, :email, presence: true
+          validates :phone_number, presence: true, length: { maximum: 13 }
+          validates :email, format: {
+            with: URI::MailTo::EMAIL_REGEXP,
+            message: "is invalid."
+          }
+
+          validates_with K2ConnectRuby::K2Utilities::PhoneNumberValidator
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/paybill.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module ExternalRecipient
+        class Paybill < RecipientRequest
+          include ActiveModel::Validations
+
+          attr_accessor :paybill_name, :paybill_number, :paybill_account_number
+
+          validates :paybill_name, :paybill_number, :paybill_account_number, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/recipient_request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module ExternalRecipient
+        class RecipientRequest
+          include ActiveModel::Validations
+
+          attr_accessor :type, :nickname
+
+          def initialize(kwargs)
+            kwargs.each do |key, value|
+              instance_variable_set("@#{key}", value)
+            end
+          end
+
+          def endpoint
+            K2ConnectRuby::K2Utilities::Config::K2Config.endpoint("external_recipient")
+          end
+
+          def request_body
+            {
+              type: type,
+              external_recipient: self.as_json
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient/till.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module K2ConnectRuby
+  module K2Entity
+    module K2FinancialEntities
+      module ExternalRecipient
+        class Till < RecipientRequest
+          include ActiveModel::Validations
+
+          attr_accessor :till_name, :till_number
+
+          validates :till_name, :till_number, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/k2-connect-ruby/k2_entity/k2_financial_entities/external_recipient.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Adding external recipients with either mobile_wallets, bank_accounts, till or paybill
+module K2ConnectRuby
+  module K2Entity
+    class ExternalRecipient < K2ConnectRuby::K2Entity::K2Entity
+      attr_accessor :recipients_location_url
+
+      def add_external_recipient(params)
+        params = params.with_indifferent_access
+        external_recipient = build_recipient(params)
+        raise(ArgumentError, external_recipient.errors.full_messages.first) unless external_recipient.valid?
+
+        result = K2ConnectRuby::K2Services::SendK2ConnectPostRequestService.call(
+          access_token,
+          external_recipient.endpoint,
+          external_recipient.request_body,
+        )
+        if result.success?
+          @recipients_location_url = result.data[:response_headers][:location]
+        else
+          raise(result.errors.first)
+        end
+      end
+
+      # Query/Check the status of a recently initiated Send money request
+      def query_status
+        super(recipients_location_url)
+      end
+
+      # Query specific URL
+      def query_resource(url)
+        super(url)
+      end
+
+      private
+
+      def build_recipient(params)
+        case params[:type]
+        when "mobile_wallet"
+          K2ConnectRuby::K2Entity::K2FinancialEntities::ExternalRecipient::MobileWallet.new(params)
+        when "bank_account"
+          K2ConnectRuby::K2Entity::K2FinancialEntities::ExternalRecipient::BankAccount.new(params)
+        when "till"
+          K2ConnectRuby::K2Entity::K2FinancialEntities::ExternalRecipient::Till.new(params)
+        when "paybill"
+          K2ConnectRuby::K2Entity::K2FinancialEntities::ExternalRecipient::Paybill.new(params)
+        else
+          raise(ArgumentError, "Undefined payment method.")
+        end
+      end
+    end
+  end
+end