mpesa_stk 1.3 → 3.0.0

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