mpesa_stk 1.3 → 3.0.0

data/Rakefile

@@ -1,10 +1,12 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 5.1.x   | :white_check_mark: |
+| 5.0.x   | :x:                |
+| 4.0.x   | :white_check_mark: |
+| < 4.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Tell them where to go, how often they can expect to get an update on a
+reported vulnerability, what to expect if the vulnerability is accepted or
+declined, etc.

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "mpesa_stk"
+require 'bundler/setup'
+require 'mpesa_stk'
 
 # 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.
@@ -10,5 +11,5 @@ require "mpesa_stk"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/lib/mpesa_stk/access_token.rb

@@ -1,7 +1,34 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2018 mboya
+#
+# MIT License
+#
+# 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.
+
 require 'base64'
+require 'json'
 require 'redis'
+require 'mpesa_stk/config'
 
 module MpesaStk
+  # Handles OAuth access token generation, caching, and refreshing for M-Pesa APIs
   class AccessToken
     class << self
       def call(key = nil, secret = nil)
@@ -10,34 +37,38 @@ module MpesaStk
     end
 
     def initialize(key = nil, secret = nil)
-      @key = key.nil? ? ENV['key'] : key
-      @secret = secret.nil? ? ENV['secret'] : secret
-      @redis = Redis.new
+      @key = key.nil? ? Config.fetch('key') : key
+      @secret = secret.nil? ? Config.fetch('secret') : secret
+      begin
+        @redis = Redis.new
+      rescue Redis::CannotConnectError, Redis::ConnectionError => e
+        raise StandardError, "Failed to connect to Redis: #{e.message}"
+      end
 
       load_from_redis
     end
 
-    def is_valid?
-      has_token? && !token_expired?
+    def valid?
+      token? && !token_expired?
     end
 
     def token_expired?
       expire_time = @timestamp.to_i + @expires_in.to_i
-      return expire_time < Time.now.to_i + 58
+      expire_time < Time.now.to_i + 58
     end
 
-    def has_token?
-      return !@token.nil?
+    def token?
+      !@token.nil?
     end
 
     def refresh
-      get_new_access_token
+      new_access_token
       load_from_redis
     end
 
     def load_from_redis
       data = @redis.get(@key)
-      if (data.nil? || data.empty?)
+      if data.nil? || data.empty?
         @token = nil
         @timestamp = nil
         @expires_in = nil
@@ -47,38 +78,40 @@ module MpesaStk
         @timestamp = parsed['time_stamp']
         @expires_in = parsed['expires_in']
       end
+    rescue Redis::BaseError => e
+      raise StandardError, "Redis error: #{e.message}"
     end
 
     def access_token
-      if is_valid?
-        return @token
-      else
-        refresh
-        return @token
-      end
+      refresh unless valid?
+      @token
     end
 
-    def get_new_access_token
+    def new_access_token
       response = HTTParty.get(url, headers: headers)
 
-      hash = JSON.parse(response.body).merge(Hash['time_stamp', Time.now.to_i])
+      raise StandardError, "Failed to get access token: #{response.code} - #{response.body}" unless response.success?
+
+      hash = JSON.parse(response.body).merge({ 'time_stamp' => Time.now.to_i })
       @redis.set @key, hash.to_json
+    rescue Redis::BaseError => e
+      raise StandardError, "Redis error while saving token: #{e.message}"
     end
 
     private
 
     def url
-      "#{ENV['base_url']}#{ENV['token_generator_url']}"
+      "#{Config.fetch('base_url')}#{Config.fetch('token_generator_url')}"
     end
 
     def headers
       encode = encode_credentials @key, @secret
       {
-        "Authorization" => "Basic #{encode}"
+        'Authorization' => "Basic #{encode}"
       }
     end
 
-    def encode_credentials key, secret
+    def encode_credentials(key, secret)
       credentials = "#{key}:#{secret}"
       Base64.encode64(credentials).split("\n").join
     end

data/lib/mpesa_stk/account_balance.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Query account balance for a PayBill or Till number.
+  class AccountBalance < Client
+    class << self
+      def call(**options)
+        new(**options).query_balance
+      end
+    end
+
+    def query_balance
+      post(
+        'account_balance_url',
+        {
+          Initiator: option('initiator'),
+          SecurityCredential: option('security_credential'),
+          CommandID: 'AccountBalance',
+          PartyA: option('business_short_code', :party_a),
+          IdentifierType: @options.fetch(:identifier_type, '4'),
+          ResultURL: option('result_url'),
+          QueueTimeOutURL: option('queue_timeout_url')
+        },
+        error_message: 'Failed to query account balance'
+      )
+    end
+  end
+end

data/lib/mpesa_stk/b2b.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Business-to-business payments via Daraja B2B API.
+  class B2B < Client
+    class << self
+      def call(amount, receiver_party, **options)
+        new(amount, receiver_party, **options).send_payment
+      end
+    end
+
+    attr_reader :amount, :receiver_party
+
+    def initialize(amount, receiver_party, **options)
+      super(**options)
+      @amount = amount
+      @receiver_party = receiver_party
+    end
+
+    def send_payment
+      post('b2b_url', b2b_payload, error_message: 'Failed to send B2B payment')
+    end
+
+    private
+
+    def b2b_payload
+      {
+        Initiator: option('initiator'),
+        SecurityCredential: option('security_credential'),
+        CommandID: @options.fetch(:command_id, 'BusinessPayBill'),
+        SenderIdentifierType: @options.fetch(:sender_identifier_type, '4'),
+        RecieverIdentifierType: @options.fetch(:receiver_identifier_type, '4'),
+        Amount: amount.to_s,
+        PartyA: option('business_short_code', :party_a),
+        PartyB: receiver_party,
+        AccountReference: @options.fetch(:account_reference, ''),
+        QueueTimeOutURL: option('queue_timeout_url'),
+        ResultURL: option('result_url')
+      }
+    end
+  end
+end

data/lib/mpesa_stk/b2c.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Business-to-customer payments (salary, promotions, etc.).
+  class B2C < Client
+    class << self
+      def call(amount, phone_number, **options)
+        new(amount, phone_number, **options).send_payment
+      end
+    end
+
+    attr_reader :amount, :phone_number
+
+    def initialize(amount, phone_number, **options)
+      super(**options)
+      @amount = amount
+      @phone_number = phone_number
+    end
+
+    def send_payment
+      body = {
+        InitiatorName: option('initiator_name'),
+        SecurityCredential: option('security_credential'),
+        CommandID: @options.fetch(:command_id, 'BusinessPayment'),
+        Amount: amount.to_s,
+        PartyA: option('business_short_code', :party_a),
+        PartyB: phone_number,
+        Remarks: @options.fetch(:remarks, 'Payment'),
+        QueueTimeOutURL: option('queue_timeout_url'),
+        ResultURL: option('result_url')
+      }
+      body[:Occasion] = @options[:occasion] if @options[:occasion]
+
+      post('b2c_url', body, error_message: 'Failed to send B2C payment')
+    end
+  end
+end

data/lib/mpesa_stk/c2b.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Register C2B URLs and simulate customer-to-business payments.
+  class C2B < Client
+    class << self
+      def register(**options)
+        new(**options).register
+      end
+
+      def call(amount, phone_number, **options)
+        new(**options).simulate_payment(amount, phone_number)
+      end
+    end
+
+    def register
+      body = {
+        ShortCode: option('business_short_code', :short_code),
+        ResponseType: @options.fetch(:response_type, 'Completed'),
+        ConfirmationURL: option('confirmation_url')
+      }
+      validation_url = optional_option('validation_url')
+      body[:ValidationURL] = validation_url if validation_url
+
+      post('c2b_register_url', body, error_message: 'Failed to register C2B URL')
+    end
+
+    def simulate_payment(amount, phone_number)
+      post(
+        'c2b_simulate_url',
+        {
+          ShortCode: option('business_short_code', :short_code),
+          CommandID: @options.fetch(:command_id, 'CustomerPayBillOnline'),
+          Amount: amount.to_s,
+          Msisdn: phone_number,
+          BillRefNumber: @options.fetch(:bill_ref_number, '')
+        },
+        error_message: 'Failed to simulate C2B payment'
+      )
+    end
+  end
+end

data/lib/mpesa_stk/client.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'date'
+require 'json'
+require 'mpesa_stk/config'
+require 'mpesa_stk/access_token'
+
+module MpesaStk
+  # Shared OAuth, HTTP, and configuration helpers for Daraja API clients
+  class Client
+    AUTH_KEYS = %i[key secret].freeze
+
+    def initialize(key: nil, secret: nil, **options)
+      @key = key
+      @secret = secret
+      @options = options
+    end
+
+    def token
+      @token ||= AccessToken.call(@key, @secret)
+    end
+
+    def post(path_env_key, body, error_message: 'Request failed')
+      url = "#{Config.fetch('base_url')}#{Config.fetch(path_env_key)}"
+      response = HTTParty.post(url, headers: json_headers, body: body.to_json)
+
+      raise StandardError, "#{error_message}: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    def json_headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def stk_timestamp
+      DateTime.now.strftime('%Y%m%d%H%M%S').to_i
+    end
+
+    def stk_password(short_code, passkey, timestamp = stk_timestamp)
+      Base64.encode64("#{short_code}#{passkey}#{timestamp}").delete("\n")
+    end
+
+    def random_reference(length = 5)
+      charset = Array('A'..'Z') + Array('a'..'z')
+      Array.new(length) { charset.sample }.join
+    end
+
+    def option(env_key, keyword_key = nil)
+      keyword_key ||= env_key.to_s.tr('-', '_').to_sym
+      Config.fetch(env_key.to_s, @options[keyword_key])
+    end
+
+    def optional_option(env_key, keyword_key = nil)
+      keyword_key ||= env_key.to_s.tr('-', '_').to_sym
+      Config.env(env_key.to_s, @options[keyword_key])
+    end
+
+    def self.extract_auth_options(kwargs)
+      kwargs.slice(*AUTH_KEYS)
+    end
+  end
+end

data/lib/mpesa_stk/config.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MpesaStk
+  # Central configuration: ENV defaults with optional overrides via MpesaStk.configure
+  class Config
+    class << self
+      attr_writer :settings
+
+      def settings
+        @settings ||= {}
+      end
+
+      def configure
+        yield(settings)
+      end
+
+      def env(name, override = nil)
+        override = nil if override.respond_to?(:empty?) && override.empty?
+
+        value = settings[name.to_sym]
+        value = settings[name.to_s] if value.nil? && settings.key?(name.to_s)
+        value = override unless override.nil?
+        value = ENV.fetch(name.to_s, nil) if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+        value
+      end
+
+      def fetch(name, override = nil, label: nil)
+        value = env(name, override)
+        raise ArgumentError, "#{label || name} is not defined" if value.nil? || value.to_s.empty?
+
+        value
+      end
+    end
+  end
+end

data/lib/mpesa_stk/imsi.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Check customer account type indicator (ATI) via IMSI API.
+  class IMSI < Client
+    class << self
+      def call(customer_number, version: 'v1', **options)
+        new(**options).check_ati(customer_number, version)
+      end
+    end
+
+    def check_ati(customer_number, version = 'v1')
+      endpoint = version.to_s == 'v2' ? '/imsi/v2/checkATI' : '/imsi/v1/checkATI'
+      url = "#{Config.fetch('base_url')}#{endpoint}"
+      response = HTTParty.post(
+        url,
+        headers: json_headers,
+        body: { customerNumber: customer_number }.to_json
+      )
+
+      raise StandardError, "Failed to check ATI: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+  end
+end

data/lib/mpesa_stk/iot.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+require 'securerandom'
+
+module MpesaStk
+  # IoT SIM management and messaging via Safaricom SIM portal API.
+  class IoT < Client
+    class << self
+      def call(action, *args, **options)
+        new(**options).public_send(action, *args)
+      end
+
+      def list_sims(**options)
+        new(**options).get_all_sims(
+          start_at_index: options.fetch(:start_at_index, 0),
+          page_size: options.fetch(:page_size, 10)
+        )
+      end
+
+      def send_message(msisdn, message, **options)
+        new(**options).send_single_message(msisdn, message)
+      end
+    end
+
+    attr_reader :api_key, :vpn_group, :username
+
+    def initialize(key: nil, secret: nil, api_key: nil, vpn_group: nil, username: nil, **options)
+      super(key: key, secret: secret, **options)
+      @api_key = Config.env('iot_api_key', api_key) || 'Yl4S3KEcr173mbeUdYdjf147IuG3rJ824ArMkP6Z'
+      @vpn_group = Config.env('vpn_group', vpn_group) || ''
+      @username = Config.env('username', username) || ''
+    end
+
+    def get_all_sims(start_at_index: 0, page_size: 10)
+      post_request('/allsims', {
+                     vpnGroup: [vpn_group],
+                     startAtIndex: start_at_index.to_s,
+                     pageSize: page_size.to_s,
+                     username: username
+                   })
+    end
+
+    def query_lifecycle_status(msisdn)
+      post_request('/queryLifeCycleStatus', { msisdn: msisdn, vpnGroup: vpn_group, username: username })
+    end
+
+    def query_customer_info(msisdn)
+      post_request('/querycustomerinfo', { msisdn: msisdn, vpnGroup: vpn_group, username: username })
+    end
+
+    def sim_activation(msisdn)
+      post_request('/simactivation', { msisdn: msisdn, vpnGroup: vpn_group, username: username })
+    end
+
+    def get_activation_trends(start_date:, stop_date:)
+      post_request('/getactivationtrends', {
+                     vpnGroup: vpn_group,
+                     startDate: start_date,
+                     stopDate: stop_date,
+                     username: username
+                   })
+    end
+
+    def rename_asset(msisdn, asset_name)
+      post_request('/renameasset', {
+                     msisdn: msisdn,
+                     vpnGroup: vpn_group,
+                     username: username,
+                     assetName: asset_name
+                   })
+    end
+
+    def get_location_info(msisdn)
+      post_request('/getlocationinfo', { msisdn: msisdn, vpnGroup: vpn_group, username: username })
+    end
+
+    def suspend_unsuspend_sub(msisdn, product, operation)
+      post_request('/suspend_unsuspend_sub', {
+                     msisdn: msisdn,
+                     username: username,
+                     vpnGroup: vpn_group,
+                     product: product,
+                     operation: operation
+                   })
+    end
+
+    def get_all_messages(page_no: 1, page_size: 10)
+      get_request("/getallmessages?pageNo=#{page_no}&pageSize=#{page_size}", { vpnGroup: vpn_group })
+    end
+
+    def search_messages(search_value, page_no: 1, page_size: 5)
+      get_request("/searchmessages?pageNo=#{page_no}&pageSize=#{page_size}", {
+                    searchValue: search_value,
+                    vpnGroup: vpn_group,
+                    username: username
+                  })
+    end
+
+    def filter_messages(start_date:, end_date:, status: '', page_no: 1, page_size: 10)
+      get_request("/filtermessages?pageNo=#{page_no}&pageSize=#{page_size}", {
+                    startDate: start_date,
+                    endDate: end_date,
+                    status: status,
+                    vpnGroup: vpn_group,
+                    username: username
+                  })
+    end
+
+    def send_single_message(msisdn, message)
+      post_request('/sendsinglemessage', {
+                     msisdn: msisdn,
+                     message: message,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    def delete_message(message_id)
+      post_request('/deletemessage', { id: message_id, vpnGroup: vpn_group, username: username })
+    end
+
+    def delete_message_thread(msisdn)
+      post_request('/deleteMessageThread', { msisdn: msisdn, vpnGroup: vpn_group, username: username })
+    end
+
+    private
+
+    def base_url
+      "#{Config.fetch('base_url')}#{Config.fetch('iot_base_url')}"
+    end
+
+    def iot_headers(msisdn: nil)
+      headers_hash = {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json',
+        'x-correlation-conversationid' => SecureRandom.uuid,
+        'x-source-system' => 'web-portal',
+        'x-api-key' => api_key,
+        'X-App' => 'web-portal',
+        'X-MessageID' => SecureRandom.uuid
+      }
+      headers_hash['X-MSISDN'] = msisdn if msisdn
+      headers_hash
+    end
+
+    def post_request(endpoint, body)
+      response = HTTParty.post(
+        "#{base_url}#{endpoint}",
+        headers: iot_headers(msisdn: body[:msisdn]),
+        body: body.to_json
+      )
+
+      raise StandardError, "Failed IoT request: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    def get_request(endpoint, body)
+      response = HTTParty.post("#{base_url}#{endpoint}", headers: iot_headers, body: body.to_json)
+
+      raise StandardError, "Failed IoT request: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+  end
+end