mpesa_stk 1.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12e1c2a4f60b943357593f37099a3ef7e5a9f4c272a0aca0960452b504789fe0
-  data.tar.gz: 14c3633244b9867b275a1e10949f4b6880b62c04e42213c6b5b2f4ded24e4dc1
+  metadata.gz: 94ab99204952e38b30261d8fe99056e6bd73490188168fb7715678ce2441da1c
+  data.tar.gz: d2c669caa9c3188c6501e38399bf956558298eb76a8c9d101dc2d15ab4def24f
 SHA512:
-  metadata.gz: 7fe982c6d29a14a7ab22e2acc16d97b9411666c47edf664c5f77a9e0b398d7b6cf3c031bdd9c9e55003f4fb31a21ecaef65e5eeadb4f7893721c3c466ba06e57
-  data.tar.gz: c2dbf612bd39861047a24cf0497a01893ec6b0018ec20ee6f33cc8a36d0964e87172566f0090bcf4e29f076d099192dab6b0e859951029db8d32b38feb04171a
+  metadata.gz: 5e5ba51ab343854857e5cfbc47df4bdfa54c249a91287eabb56db5be22c9b3f440634f7ea6a89bfd1a393bfc1aa30639e2cc01441774b6872307ddfa26ce931d
+  data.tar.gz: ae94348ea8d875a3384e6fa64dd58ce96ee3a86fb3525b826d3ec24c41ec887e6f75d5ee6ff1a6dc981f217dcac33f69a937c1241b2c742a0d3eec59a5ce8ae5

data/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,70 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ master ]
+  schedule:
+    - cron: '41 13 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'ruby' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://git.io/codeql-language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

data/.github/workflows/cop.yml

@@ -1,22 +1,26 @@
 name: Cop
-on: [push]
+on: [push, pull_request]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Rubocop checks
-        uses: gimenete/rubocop-action@1.0
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - uses: actions/checkout@v2
-      - name: Set up Ruby 2.6
-        uses: actions/setup-ruby@v1
+      - uses: actions/checkout@v4
+      
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.6
-      - name: Rails Test
+          ruby-version: "3.2"
+          bundler-cache: true
+
+      - name: Verify bundle installation
         run: |
-          gem install bundler
-          bundle install
-          bundle exec rake test
+          bundle --version
+          bundle check || bundle install
+
+      - name: Rubocop checks
+        run: bundle exec rubocop
+        continue-on-error: false
+
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -9,6 +9,8 @@
 
 .env
 .DS_Store
+._*
+**/._*
 *.gem
 dump.rdb
 

data/.rubocop.yml

@@ -0,0 +1,63 @@
+# The behavior of RuboCop can be controlled via the .rubocop.yml
+# configuration file. It makes it possible to enable/disable
+# certain cops (checks) and to alter their behavior if they accept
+# any parameters. The file can be placed either in your home
+# directory or in some project directory.
+#
+# RuboCop will start looking for the configuration file in the directory
+# where the inspected file is and continue its way up to the root directory.
+#
+# See https://docs.rubocop.org/rubocop/configuration
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.6
+  Exclude:
+    - 'vendor/**/*'
+    - 'test/**/*'
+    - 'spec/**/*'
+    - '**/._*'
+
+# Disable Gemspec/DevelopmentDependencies - it's standard practice for gems
+# to specify dev dependencies in gemspec
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Allow longer lines for method signatures and complex API calls
+Layout/LineLength:
+  Max: 130
+  Exclude:
+    - '**/*.gemspec'
+
+# Allow longer methods for API classes that need to handle many parameters
+Metrics/MethodLength:
+  Max: 15
+
+# Allow longer classes for comprehensive API implementations
+Metrics/ClassLength:
+  Max: 150
+
+# Allow more complex methods for initialization with many parameters
+# API classes need to handle many configuration options
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+# Allow more parameters for API classes that need flexibility
+# Some classes like Push need many optional parameters for different use cases
+Metrics/ParameterLists:
+  Max: 10
+  CountKeywordArgs: true
+  MaxOptionalParameters: 6
+
+# Allow get_ prefix for private validation/accessor methods
+Naming/AccessorMethodName:
+  Enabled: true
+  Exclude:
+    - 'lib/mpesa_stk/**/*'

data/.sample.env

@@ -1,10 +1,31 @@
 base_url="https://sandbox.safaricom.co.ke"
 token_generator_url="/oauth/v1/generate?grant_type=client_credentials"
 process_request_url="/mpesa/stkpush/v1/processrequest"
+transaction_status_url="/mpesa/transactionstatus/v1/query"
+stk_push_query_url="/mpesa/stkpushquery/v1/query"
+b2c_url="/mpesa/b2c/v1/paymentrequest"
+b2b_url="/mpesa/b2b/v1/paymentrequest"
+c2b_register_url="/mpesa/c2b/v1/registerurl"
+c2b_simulate_url="/mpesa/c2b/v1/simulate"
+account_balance_url="/mpesa/accountbalance/v1/query"
+reversal_url="/mpesa/reversal/v1/request"
+ratiba_url="/standingorder/v1/createStandingOrderExternal"
+iot_base_url="/simportal/v1"
+pull_transactions_register_url="/pulltransactions/v1/register"
+pull_transactions_query_url="/pulltransactions/v1/query"
 
 key=""
 secret=""
 business_short_code=""
 business_passkey=""
 callback_url="https://api.endpoint/callback"
-till_number=""
+confirmation_url="https://api.endpoint/confirmation"
+till_number=""
+initiator=""
+initiator_name=""
+security_credential=""
+result_url="https://api.endpoint/result"
+queue_timeout_url="https://api.endpoint/queue_timeout"
+iot_api_key="Yl4S3KEcr173mbeUdYdjf147IuG3rJ824ArMkP6Z"
+vpn_group=""
+username=""

data/CHANGELOG.md

@@ -0,0 +1,259 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0] - 2026-05-25
+
+### Changed
+
+- **Breaking:** Unified public API on `.call` (and `.register` for URL registration endpoints).
+- **Breaking:** Replaced string-key option hashes with keyword arguments (`key:`, `secret:`, `business_short_code:`, etc.).
+- **Breaking:** `MpesaStk::PushPayment` removed; use `MpesaStk::Push.call(amount, phone, type: :pay_bill | :buy_goods)`. PayBill is the default.
+- **Breaking:** IoT entry points: use `IoT.list_sims`, `IoT.send_message`, or `IoT.call(:method_name, ...)`. Removed `IoT.sims` / `IoT.messaging` factories.
+- Added `MpesaStk::Client` base class and `MpesaStk::Config` for shared HTTP, OAuth, and configuration.
+- Added `MpesaStk.configure` block and `MPESA_STK_SKIP_DOTENV` to control Dotenv loading.
+
+### Added
+
+- `MIGRATION.md` with a full 2.x → 3.0 upgrade guide.
+
+## [2.0.0] - 2025-01-XX
+
+### Added
+
+#### New API Endpoints
+
+- **Transaction Status Query** (`MpesaStk::TransactionStatus`)
+  - Query the status of any M-Pesa transaction
+  - Supports querying by transaction ID
+  - Full error handling and response parsing
+
+- **STK Push Query** (`MpesaStk::StkPushQuery`)
+  - Query the status of STK Push transactions
+  - Check payment request status using CheckoutRequestID
+
+- **Business to Customer (B2C)** (`MpesaStk::B2C`)
+  - Send money from business to customer
+  - Supports salary payments, promotions, and other B2C transactions
+  - Configurable command IDs and remarks
+
+- **Business to Business (B2B)** (`MpesaStk::B2B`)
+  - Send money from business to business
+  - Supports PayBill to PayBill and PayBill to Buy Goods transactions
+  - Full support for sender and receiver account references
+
+- **Customer to Business (C2B)** (`MpesaStk::C2B`)
+  - Register C2B validation and confirmation URLs
+  - Simulate C2B payments for testing
+  - Complete C2B payment flow support
+
+- **Account Balance Query** (`MpesaStk::AccountBalance`)
+  - Query account balance for PayBill or Till Number
+  - Supports both Initiator and PartyA queries
+
+- **Transaction Reversal** (`MpesaStk::Reversal`)
+  - Reverse M-Pesa transactions
+  - Supports full and partial reversals
+  - Configurable timeout and result URLs
+
+- **M-Pesa Ratiba (Standing Orders)** (`MpesaStk::Ratiba`)
+  - Create recurring payment standing orders
+  - Schedule automatic payments
+  - Manage subscription-based payments
+
+- **IoT SIM Management & Messaging** (`MpesaStk::IoT`)
+  - **SIM Operations:**
+    - Get all SIMs with pagination
+    - Query lifecycle status
+    - Query customer information
+    - SIM activation
+    - Get activation trends
+    - Rename assets
+    - Get location information
+    - Suspend/unsuspend subscriptions
+  - **Messaging Operations:**
+    - Get all messages with pagination
+    - Search messages
+    - Filter messages by date/status
+    - Send single messages to IoT devices
+    - Delete messages and message threads
+
+- **IMSI/SWAP Operations** (`MpesaStk::IMSI`)
+  - Check ATI (Access Transaction Information)
+  - Query IMSI and SIM swap information
+  - Supports both v1 and v2 API versions
+  - Useful for fraud prevention and SIM verification
+
+- **Pull Transactions** (`MpesaStk::PullTransactions`)
+  - Register pull transaction callback URLs
+  - Query historical transactions
+  - Retrieve transaction data for reconciliation
+
+#### Testing Infrastructure
+
+- Comprehensive test suite with 148 tests covering all features
+- Test files for all new API endpoints:
+  - `test/transaction_status_test.rb`
+  - `test/stk_push_query_test.rb`
+  - `test/b2c_test.rb`
+  - `test/b2b_test.rb`
+  - `test/c2b_test.rb`
+  - `test/account_balance_test.rb`
+  - `test/reversal_test.rb`
+  - `test/ratiba_test.rb`
+  - `test/iot_test.rb`
+  - `test/imsi_test.rb`
+  - `test/pull_transactions_test.rb`
+- Enhanced `MockRedis` class for isolated testing without external Redis dependency
+- Improved test helper with comprehensive environment variable setup
+- All tests use WebMock for HTTP request stubbing
+
+#### Documentation
+
+- Comprehensive README.md update with:
+  - Detailed API reference for all endpoints
+  - Usage examples using both ENV variables and hash parameters
+  - Descriptions for each API endpoint explaining their purpose
+  - Consolidated response format and error handling sections
+  - Quick start examples
+  - Complete configuration guide
+- Updated `.sample.env` with all new environment variables
+- Clear documentation of required vs optional parameters
+
+#### Configuration
+
+- Added support for hash-based parameter passing for all APIs
+- Enhanced ENV variable support for all new endpoints
+- Improved error messages for missing configuration
+- Standardized configuration access across all classes
+
+### Changed
+
+#### Dependencies
+
+- Added explicit `base64` dependency (>= 0.1.0) for Ruby 3.4+ compatibility
+- Added explicit `csv` dependency (>= 3.0.0) for Ruby 3.4+ compatibility
+- Updated `minitest` to ~> 5.20 for Ruby 3.3+ compatibility
+- Updated `pry` to ~> 0.12 for compatibility
+- Updated `pry-nav` to ~> 0.3 for compatibility
+- Updated `httparty` constraint to < 0.22.0
+- All dependencies now compatible with Ruby 3.3+
+
+#### Code Quality
+
+- Improved error handling across all API classes
+- Standardized error messages and exception types
+- Enhanced HTTP response validation
+- Better handling of missing configuration
+- Improved code consistency across all classes
+- Added `frozen_string_literal: true` to gemspec
+
+#### Test Infrastructure
+
+- Fixed circular require warnings in Ruby 3.3+
+- Improved test isolation with better MockRedis implementation
+- Enhanced test helper with proper warning suppression
+- Better test organization and structure
+
+#### CI/CD
+
+- Updated GitHub Actions workflow:
+  - Updated `actions/checkout` to v4
+  - Updated Ruby setup action to `ruby/setup-ruby@v1`
+  - Updated Ruby version to 3.1
+  - Added `bundler-cache: true` for faster builds
+  - Added `pull_request` trigger
+
+### Fixed
+
+- Fixed Ruby 3.4+ compatibility warnings for `base64` and `csv` gems
+- Fixed circular require warnings in test suite (Ruby 3.3+)
+- Fixed `MockRedis` shared storage issue in tests
+- Fixed assertion method names in tests (`assert_not_equal` → `refute_equal`)
+- Fixed syntax error in `MpesaStk::IMSI` class
+- Improved error handling for Redis connection failures
+- Fixed generic exception handling (changed to `ArgumentError` where appropriate)
+
+### Improved
+
+- Better separation of concerns across API classes
+- More consistent API design patterns
+- Enhanced documentation and examples
+- Improved code maintainability
+- Better error messages for debugging
+
+## [1.3.0] - Previous Version
+
+### Features
+
+- STK Push payment initiation
+- Access token management with Redis caching
+- Support for multiple applications with custom credentials
+- Basic error handling and response parsing
+
+---
+
+## Version History
+
+- **2.0.0** - Major release with comprehensive API coverage, full test suite, and Ruby 3.3+ compatibility
+- **1.3.0** - Initial stable release with STK Push functionality
+
+---
+
+## Migration Guide
+
+### Upgrading from 1.3.x to 2.0.0
+
+1. **Update Dependencies:**
+   ```bash
+   bundle update mpesa_stk
+   ```
+
+2. **New Environment Variables:**
+   Add the following to your `.env` file (see `.sample.env` for complete list):
+   - `transaction_status_url`
+   - `stk_push_query_url`
+   - `b2c_url`, `b2b_url`
+   - `c2b_register_url`, `c2b_simulate_url`
+   - `account_balance_url`
+   - `reversal_url`
+   - `ratiba_url`
+   - `iot_base_url`, `iot_api_key`, `vpn_group`, `username`
+   - `imsi_v1_url`, `imsi_v2_url`
+   - `pull_transactions_register_url`, `pull_transactions_query_url`
+   - `initiator`, `initiator_name`, `security_credential`
+   - `result_url`, `queue_timeout_url`, `confirmation_url`
+
+3. **Ruby Version:**
+   Ensure you're using Ruby 2.6.0 or higher (Ruby 3.3+ recommended)
+
+4. **Redis:**
+   Redis 4.0+ is now required
+
+5. **API Changes:**
+   - All existing STK Push APIs remain backward compatible
+   - New APIs follow consistent patterns with both ENV and hash parameter support
+   - Error handling has been improved but maintains backward compatibility
+
+### Breaking Changes
+
+None - This release maintains full backward compatibility with version 1.3.x.
+
+---
+
+## Contributors
+
+- mboya
+- cess
+
+---
+
+## Links
+
+- [GitHub Repository](https://github.com/mboya/mpesa_stk)
+- [RubyGems](https://rubygems.org/gems/mpesa_stk)
+- [Safaricom Developer Portal](https://developer.safaricom.co.ke/)
+

data/Gemfile

@@ -1,6 +1,10 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in mpesa_stk.gemspec
 gemspec
+
+gem 'simplecov', '~> 0.22.0', group: :development

data/Gemfile.lock

@@ -1,51 +1,97 @@
 PATH
   remote: .
   specs:
-    mpesa_stk (1.3)
-      httparty (>= 0.15.6, < 0.19.0)
+    mpesa_stk (3.0.0)
+      base64 (>= 0.1.0)
+      csv (>= 3.0.0)
+      httparty (>= 0.15.6, < 0.25.0)
+      redis (>= 4.0)
       redis-namespace (~> 1.5, >= 1.5.3)
       redis-rack (~> 2.0, >= 2.0.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
-      public_suffix (>= 2.0.2, < 5.0)
-    coderay (1.1.2)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    dotenv (2.7.5)
-    hashdiff (1.0.1)
-    httparty (0.18.1)
-      mime-types (~> 3.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    coderay (1.1.3)
+    connection_pool (3.0.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    csv (3.3.5)
+    docile (1.4.1)
+    dotenv (3.2.0)
+    hashdiff (1.2.1)
+    httparty (0.24.2)
+      csv
+      mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
-    method_source (0.8.2)
-    mime-types (3.3.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2020.0512)
-    minitest (5.14.0)
-    multi_xml (0.6.0)
-    pry (0.10.4)
-      coderay (~> 1.1.0)
-      method_source (~> 0.8.1)
-      slop (~> 3.4)
-    pry-nav (0.2.4)
-      pry (>= 0.9.10, < 0.11.0)
-    public_suffix (4.0.4)
-    rack (2.2.2)
-    rake (13.0.1)
-    redis (4.2.1)
-    redis-namespace (1.7.0)
-      redis (>= 3.0.4)
-    redis-rack (2.1.2)
+    json (2.19.5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    method_source (1.1.0)
+    mini_mime (1.1.5)
+    minitest (5.27.0)
+    multi_xml (0.9.1)
+      bigdecimal (>= 3.1, < 5)
+    parallel (1.28.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-nav (1.0.0)
+      pry (>= 0.9.10, < 0.15)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rack (2.2.23)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    redis (5.4.1)
+      redis-client (>= 0.22.0)
+    redis-client (0.29.0)
+      connection_pool
+    redis-namespace (1.11.0)
+      redis (>= 4)
+    redis-rack (2.1.4)
       rack (>= 2.0.8, < 3)
       redis-store (>= 1.2, < 2)
-    redis-store (1.8.2)
-      redis (>= 4, < 5)
-    safe_yaml (1.0.5)
-    slop (3.6.0)
-    webmock (3.8.3)
-      addressable (>= 2.3.6)
+    redis-store (1.11.0)
+      redis (>= 4, < 6)
+    regexp_parser (2.12.0)
+    rexml (3.4.4)
+    rubocop (1.86.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
 
@@ -53,14 +99,16 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler
-  dotenv (= 2.7.5)
-  minitest (~> 5.0)
+  bundler (~> 2.0)
+  dotenv (~> 3.0)
+  minitest (~> 5.20)
   mpesa_stk!
-  pry (~> 0.10.4)
-  pry-nav (~> 0.2.4)
+  pry (~> 0.14)
+  pry-nav (~> 1.0)
   rake (>= 12.3.3)
-  webmock (~> 3.0, >= 3.0.1)
+  rubocop (~> 1.0)
+  simplecov (~> 0.22.0, ~> 0.22)
+  webmock (~> 3.18)
 
 BUNDLED WITH
-   2.1.4
+   2.7.2