mpesa_stk 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '082084ffdcc3290058eadfdc3e63e59bbd257bfe29a8d346c42a29013abe8116'
-  data.tar.gz: 152156f9e4df7894afd4fe9ab9836df4ed2b4c5e17355dc33bee978b73e7a84a
+  metadata.gz: 94ab99204952e38b30261d8fe99056e6bd73490188168fb7715678ce2441da1c
+  data.tar.gz: d2c669caa9c3188c6501e38399bf956558298eb76a8c9d101dc2d15ab4def24f
 SHA512:
-  metadata.gz: a096f3653a3018fe7d2cde6e5764ba2c04f1116b055fcbe390e150e1a946b637b01e4bdcd4e3fd53bac1eb0e9d974c1e4efed733bc3f9475c7c8617eeb2411f1
-  data.tar.gz: d4b2019ef1f775f14e6180b643593a92a140530aade71d020cf5dd12cd81edb315c090b31fa10d3db0dd33419fa9dfdf489ec877a96bdd177e85802b2a57edc0
+  metadata.gz: 5e5ba51ab343854857e5cfbc47df4bdfa54c249a91287eabb56db5be22c9b3f440634f7ea6a89bfd1a393bfc1aa30639e2cc01441774b6872307ddfa26ce931d
+  data.tar.gz: ae94348ea8d875a3384e6fa64dd58ce96ee3a86fb3525b826d3ec24c41ec887e6f75d5ee6ff1a6dc981f217dcac33f69a937c1241b2c742a0d3eec59a5ce8ae5

data/.gitignore

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

data/.rubocop.yml

@@ -17,6 +17,7 @@ AllCops:
     - 'vendor/**/*'
     - 'test/**/*'
     - 'spec/**/*'
+    - '**/._*'
 
 # Disable Gemspec/DevelopmentDependencies - it's standard practice for gems
 # to specify dev dependencies in gemspec

data/CHANGELOG.md

@@ -5,6 +5,21 @@ 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

data/Gemfile

@@ -6,3 +6,5 @@ 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,10 +1,10 @@
 PATH
   remote: .
   specs:
-    mpesa_stk (2.0.0)
+    mpesa_stk (3.0.0)
       base64 (>= 0.1.0)
       csv (>= 3.0.0)
-      httparty (>= 0.15.6, < 0.22.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)
@@ -12,48 +12,50 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.8)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
-    bigdecimal (3.3.1)
+    bigdecimal (4.1.2)
     coderay (1.1.3)
     connection_pool (3.0.2)
     crack (1.0.1)
       bigdecimal
       rexml
     csv (3.3.5)
-    dotenv (2.8.1)
+    docile (1.4.1)
+    dotenv (3.2.0)
     hashdiff (1.2.1)
-    httparty (0.21.0)
+    httparty (0.24.2)
+      csv
       mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
-    json (2.17.1)
+    json (2.19.5)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    method_source (0.9.2)
+    method_source (1.1.0)
     mini_mime (1.1.5)
-    minitest (5.26.2)
-    multi_xml (0.7.2)
-      bigdecimal (~> 3.1)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    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.6.0)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    pry-nav (0.3.0)
-      pry (>= 0.9.10, < 0.13.0)
-    public_suffix (7.0.0)
+    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.21)
+    rack (2.2.23)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
     redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.26.2)
+    redis-client (0.29.0)
       connection_pool
     redis-namespace (1.11.0)
       redis (>= 4)
@@ -62,27 +64,33 @@ GEM
       redis-store (>= 1.2, < 2)
     redis-store (1.11.0)
       redis (>= 4, < 6)
-    regexp_parser (2.11.3)
+    regexp_parser (2.12.0)
     rexml (3.4.4)
-    rubocop (1.81.7)
+    rubocop (1.86.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.48.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      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.1.0)
-    webmock (3.26.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)
@@ -92,13 +100,14 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 2.0)
-  dotenv (~> 2.8)
+  dotenv (~> 3.0)
   minitest (~> 5.20)
   mpesa_stk!
-  pry (~> 0.12)
-  pry-nav (~> 0.3)
+  pry (~> 0.14)
+  pry-nav (~> 1.0)
   rake (>= 12.3.3)
   rubocop (~> 1.0)
+  simplecov (~> 0.22.0, ~> 0.22)
   webmock (~> 3.18)
 
 BUNDLED WITH

data/MIGRATION.md

@@ -0,0 +1,77 @@
+# Migrating from 2.x to 3.0
+
+Version 3.0 unifies the public API around `.call` (and `.register` where registration is not a payment). String-key option hashes are removed; use keyword arguments instead.
+
+## Configuration
+
+ENV variables from `.sample.env` still work. Optional programmatic overrides:
+
+```ruby
+MpesaStk.configure do |c|
+  c[:business_short_code] = '174379'
+  c[:key] = 'your_key'
+end
+```
+
+Set `MPESA_STK_SKIP_DOTENV=true` in production if your host app loads environment variables itself.
+
+## API changes
+
+| 2.x | 3.0 |
+|-----|-----|
+| `MpesaStk::PushPayment.call(amount, phone)` | `MpesaStk::Push.call(amount, phone)` |
+| `MpesaStk::Push.pay_bill(amount, phone, hash)` | `MpesaStk::Push.call(amount, phone, **opts)` |
+| `MpesaStk::Push.buy_goods(amount, phone, hash)` | `MpesaStk::Push.call(amount, phone, type: :buy_goods, till_number: '...')` |
+| `MpesaStk::B2C.pay(amount, phone, hash)` | `MpesaStk::B2C.call(amount, phone, remarks: '...')` |
+| `MpesaStk::B2B.pay(amount, receiver, hash)` | `MpesaStk::B2B.call(amount, receiver, **opts)` |
+| `MpesaStk::C2B.register_url(hash)` | `MpesaStk::C2B.register(**opts)` |
+| `MpesaStk::C2B.simulate(amount, phone, hash)` | `MpesaStk::C2B.call(amount, phone, **opts)` |
+| `MpesaStk::StkPushQuery.query(id, hash)` | `MpesaStk::StkPushQuery.call(id, **opts)` |
+| `MpesaStk::TransactionStatus.query(id, hash)` | `MpesaStk::TransactionStatus.call(id, **opts)` |
+| `MpesaStk::AccountBalance.query(hash)` | `MpesaStk::AccountBalance.call(**opts)` |
+| `MpesaStk::Reversal.reverse(id, amount, hash)` | `MpesaStk::Reversal.call(id, amount, **opts)` |
+| `MpesaStk::Ratiba.create_standing_order(hash)` | `MpesaStk::Ratiba.call(amount:, party_a:, start_date:, end_date:, **opts)` |
+| `MpesaStk::PullTransactions.register(hash)` | `MpesaStk::PullTransactions.register(**opts)` |
+| `MpesaStk::PullTransactions.query(start, end, hash)` | `MpesaStk::PullTransactions.call(start, end, **opts)` |
+| `MpesaStk::IMSI.check_ati(phone, hash, version:)` | `MpesaStk::IMSI.call(phone, version: 'v1', **opts)` |
+| `MpesaStk::IoT.sims({}).get_all_sims` | `MpesaStk::IoT.list_sims` or `MpesaStk::IoT.call(:get_all_sims, **opts)` |
+| `MpesaStk::IoT.messaging({}).send_single_message(msisdn, msg)` | `MpesaStk::IoT.send_message(msisdn, msg)` |
+
+## Hash to keyword examples
+
+```ruby
+# 2.x
+MpesaStk::B2C.pay(100, '254712345678', { 'command_id' => 'SalaryPayment', 'key' => 'k', 'secret' => 's' })
+
+# 3.0
+MpesaStk::B2C.call(100, '254712345678', command_id: 'SalaryPayment', key: 'k', secret: 's')
+```
+
+```ruby
+# 2.x
+MpesaStk::Push.pay_bill(100, '254712345678', { 'business_short_code' => '174379', 'callback_url' => 'https://...' })
+
+# 3.0
+MpesaStk::Push.call(100, '254712345678', business_short_code: '174379', callback_url: 'https://...')
+```
+
+## IoT
+
+Prefer shortcuts:
+
+```ruby
+MpesaStk::IoT.list_sims(page_size: 20)
+MpesaStk::IoT.send_message('0110100606', 'Hello device')
+```
+
+Or dispatch any instance method:
+
+```ruby
+MpesaStk::IoT.call(:query_lifecycle_status, '0110100606')
+```
+
+## Internal changes
+
+- Shared `MpesaStk::Client` base for HTTP and OAuth
+- `MpesaStk::Config` for ENV / configure overrides
+- Removed per-class `get_*` helpers and string-hash constructors