paystack_sdk 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a18abe45774bda30eff6f91a3e93ba55066d9ef4f04ddfc690792edc8b005d94
-  data.tar.gz: 652cc2b936ac3a7211290ad6a6f561d57132fd825588232fab724a0b2378cfa7
+  metadata.gz: a47ad018e13e2e59c645d1834e38ff503c74573670e90fd3e286ff090cc0768d
+  data.tar.gz: 3ff34906416d4d3d33315af10537113fbc64189b002a95c5d27b6df32b9c5592
 SHA512:
-  metadata.gz: 5fcb8324376b91af1c71e894309789fb69a4eeefff5d4a1fa93c190a66c9c01489d5a8a9b4003f8416fbff3ffe5d3474ec6ec49ab9c1a58ed7fb16ebf095c04a
-  data.tar.gz: b094c91f15744f8c02ca9e493d7aa6ab7b9c24f6f0e25cc8e1a94d32bc9d3101aa713a97ff074000e365e1f1857d26735bd99016e82a480b7da839e6be9b349e
+  metadata.gz: d041e1cb40107e93fb39e27220c5f33c52baa8e6167a7812c907a1272311bfa7a782f5b1e9e358afa8e5900c56408f62892e35b5b4b3e71fb37b44f1228aa488
+  data.tar.gz: e1f0f1ffb505ad4a0b6c3c8944ada4e4fd61d9ab29cf7f87551c8697ba606f94bd975068396d3ca5b2226d24ccba38e7f431fab2204b177ccd5da5a1f97176fb

data/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.2.0] - 2026-10-09
+
+### Breaking
+
+- `Transactions` is now generated from Paystack's OpenAPI spec and takes keyword arguments instead of payload hashes. Method names are unchanged.
+  - `initiate(email:, amount:, ...)`, `charge_authorization(email:, amount:, authorization_code:, ...)` and `partial_debit(email:, amount:, authorization_code:, currency:, ...)` no longer accept a hash; use `initiate(**params)` to migrate.
+  - `fetch(id:)` replaces `fetch(transaction_id)`; `timeline(id:)` replaces `timeline(id_or_reference)`.
+  - `list`, `totals` and `export` take named filters (`from`, `to`, `status`, `customer_id`, `settlement`, ...) instead of `**params`, so a misspelt filter now raises `ArgumentError`. `list` no longer defaults `per_page: 50, page: 1`; Paystack's own defaults apply.
+  - The numeric customer filter on `list` and `export` is `customer_id:` (it sends Paystack's `customer`).
+- `Charges` is now generated from Paystack's OpenAPI spec and takes keyword arguments instead of payload hashes.
+  - `mobile_money(email:, amount:, mobile_money:, currency: nil, reference: nil, metadata: nil)` no longer accepts a hash; use `mobile_money(**params)` to migrate. It no longer sends `callback_url`, which neither Paystack's docs nor its spec list for `POST /charge` (the API does not validate it either).
+  - `submit_otp(otp:, reference:)` no longer accepts a hash.
+
+- `Banks` is regenerated from Paystack's OpenAPI spec, `Miscellaneous` is new, and `Verification` (`client.verification`) is removed. All take keyword arguments.
+  - `verification.resolve_account(account_number:, bank_code:)` is now `banks.resolve_account_number(account_number:, bank_code:)`.
+  - `verification.validate_account(hash)` is now `banks.validate_account(account_name:, account_number:, account_type:, bank_code:, country_code:, document_type:, document_number: nil)`.
+  - `verification.resolve_card_bin(bin)` is now `miscellaneous.resolve_card_bin(bin:)`. New: `miscellaneous.list_countries` and `miscellaneous.list_states(country:)`.
+  - `banks.list` takes named filters instead of a hash (`per_page:` is sent as `perPage`, `next_cursor:` as `next`) and now accepts every filter Paystack documents (`country`, `type`, `gateway`, `use_cursor`, ...). Its `type` enum uses `ghipss` (the spec's `ghipps` is a typo), and `currency` still accepts `USD`.
+- `TransferRecipients` is now generated from Paystack's OpenAPI spec and takes keyword arguments instead of payload hashes. Method names are unchanged.
+  - `create(type:, name:, account_number:, bank_code:, ...)` no longer accepts a hash; use `create(**params)` to migrate. `type` is checked against Paystack's list (`nuban`, `ghipss`, `mobile_money`, `basa`, `authorization`).
+  - `fetch(id_or_code:)`, `update(id_or_code:, name:, email:)` and `delete(id_or_code:)` replace `recipient_code:`. The value can be the recipient code or its numeric ID. `update` takes `name:` and `email:` instead of a `params:` hash; `name` is optional, as the API accepts an update with only `email` (docs say `name` is required; checked against the test API).
+  - `list` takes `per_page:`, `page:`, `use_cursor:`, `next_cursor:` and `previous:` instead of a query hash. `perPage` is what Paystack's docs name the page size; the API honours it. `from` and `to` are in the docs but the API ignores them, so they are not offered.
+- `Customers` is now generated from Paystack's OpenAPI spec and takes keyword arguments instead of payload hashes. Method names are unchanged.
+  - `create(email:, ...)`, `set_risk_action(customer:, risk_action: nil)` and `deactivate_authorization(authorization_code:)` no longer accept a hash; use `create(**params)` to migrate.
+  - `fetch(email_or_code:)` replaces `fetch(email_or_code)` (the keyword is the path variable's name in Paystack's docs; it takes an email or a customer code); `update(code:, first_name: nil, ...)` replaces `update(code, payload)`; `validate(code:, ...)` replaces `validate(code, payload)`.
+  - `validate` now requires `first_name`, `last_name`, `type`, `country`, `bvn`, `bank_code` and `account_number`, as Paystack does (the test API answers 400 without each). It previously did not require `bvn` or the names.
+  - `list` takes named filters (`per_page`, `page`, `from`, `to`, `use_cursor`, `next_cursor`, `previous`) instead of `**params`, and no longer defaults `per_page: 50, page: 1`; Paystack's own defaults apply.
+  - `metadata` on `create` and `update` must be a Hash; it is sent as a JSON object (Paystack rejects a JSON string).
+- `Transfers` is now generated from Paystack's OpenAPI spec and takes keyword arguments instead of payload hashes. Existing method names are unchanged.
+  - `create(source:, amount:, recipient:, reference:, reason: nil, currency: nil)` no longer accepts a hash; use `create(**params)` to migrate. `reference` is now required, as Paystack's docs and spec both require it, and `currency` must be one of NGN, ZAR, KES, GHS.
+  - `fetch(id_or_code:)` replaces `fetch(id:)`, using the docs' name for the path variable (it takes a transfer ID or a `TRF_` code). The request is unchanged.
+  - `list` takes named filters (`per_page`, `page`, `from`, `to`, `recipient`, `status`, and cursor pagination with `use_cursor`, `next_cursor`, `previous`) instead of a query hash, so a misspelt filter now raises `ArgumentError`. `per_page` is sent as `perPage`.
+
+### Fixed
+
+- Values placed in URL paths (references, codes, ids, card BINs) are now escaped, and `.` / `..` are refused with `PaystackSdk::InvalidValueError` before any request is sent. Previously a value such as `".."` was resolved by the URL builder into a different endpoint (`transactions.verify(reference: "..")` called `/transaction`), and `/`, `?` or `#` in a value changed the path or query. Affects `transactions` (`verify`, `fetch`, `timeline`), `transfers` (`fetch`, `verify`), `transfer_recipients` (`fetch`, `update`, `delete`), `customers` (`fetch`, `update`, `validate`) and `miscellaneous` (`resolve_card_bin`).
+- `Response#[]` and `Response#key?` returned `nil`/`false` for every key on real Paystack bodies (string keys). Both now accept strings or symbols.
+- `Customers#deactivate_authorization` called a non-existent endpoint (`customer/deactivate_authorization`). It now posts to Paystack's documented `POST /customer/authorization/deactivate`.
+- `429` responses now raise `RateLimitError` (previously swallowed as a client error because the `400..499` branch matched first). `retry_after` is read from Paystack's `x-ratelimit-reset` header (nil when absent) instead of the undocumented `Retry-After`.
+
+### Added
+
+- `Client#live?` and `Client.new(..., sandbox_only: true)`: the client refuses to be built with anything but an `sk_test_` key (or a pre-built connection that sends one), raising `ArgumentError` before any request.
+- `Response#paid?(amount: nil, currency: nil)` (call succeeded, `status` is `"success"`, and the amount and currency match if given) and `Response#status?(value)`.
+- `spec/sandbox/`: specs against Paystack's real test API, skipped unless `PAYSTACK_TEST_SECRET_KEY` is set to an `sk_test_` key. They confirm that `charge_authorization` charges a saved reusable card.
+- `client.refunds`, generated from Paystack's OpenAPI spec: `create(transaction:, amount: nil, currency: nil, customer_note: nil, merchant_note: nil)`, `list`, `fetch(id:)` and `retry_with_customer_details(id:, refund_account_details:)`. `transaction` takes the transaction reference or its numeric ID; leave `amount` out for a full refund. `list` filters by `transaction_id:` (sent as `transaction`, documented by Paystack, absent from the spec). Both confirmed against the test API.
+- `transfer_recipients.bulk_create(batch:)` for `POST /transferrecipient/bulk`.
+- The rest of the Charge API: `charges.create`, `submit_pin`, `submit_phone`, `submit_birthday`, `submit_address` and `check_pending`. `create` takes the channel objects (`bank`, `mobile_money`, `ussd`, `eft`, `qr`, `bank_transfer`, `capitec_pay`) as keyword hashes, plus `currency`, `split_code` and `subaccount`, which Paystack documents and the test API honours although the OpenAPI spec omits them.
+- `charges.mobile_money` accepts the `mpesa_offline` and `mptill` providers Paystack documents, and an M-PESA Till `account` in place of `phone`.
+- `bin/paystack-scaffold` generates body parameters recorded as docs-only (`spec: null`) in `spec/support/paystack_contract_exceptions.yml`, as it already did for query parameters.
+- `customers` covers the rest of Paystack's Customer API: `initialize_authorization`, `verify_authorization`, `initialize_direct_debit`, `direct_debit_activation_charge` and `fetch_mandate_authorizations`, plus cursor pagination on `list` (`use_cursor`, `next_cursor`, `previous`).
+- `bin/scaffold_names.yml` entries can be a hash, `{name: ..., keywords: {path_variable: ruby_keyword}}`, so a path variable takes the Ruby keyword Paystack's docs use where the spec names it differently.
+- `bin/paystack-scaffold` applies body-field entries from `spec/support/paystack_contract_exceptions.yml` (wire name, type and description), as it already did for query parameters.
+- `transfers.bulk_create`, `export`, `resend_otp`, `disable_otp`, `finalize_disable_otp` and `enable_otp` (Paystack's Initiate Bulk Transfer, Export Transfers and Transfers Control OTP operations).
+- `transactions.export` accepts `currency`, `amount`, `settled` and `payment_page` (documented by Paystack, absent from the OpenAPI spec; confirmed to filter results against the test API) and `subaccount_code`. Paystack's docs also list `perPage` and `page` on Export, but the API ignores them, so the SDK does not offer them.
+- `PaystackSdk::Webhook` verifies Paystack webhook signatures (HMAC SHA512, constant-time) and parses events: `valid_signature?`, `verify!`, `construct_event`, `sign`, `trusted_ip?`, plus the documented `EVENTS` and `IP_ADDRESSES`. New errors: `WebhookError`, `InvalidSignatureError`, `InvalidPayloadError`.
+- `Response#meta` exposes the pagination metadata (`total`, `page`, `pageCount`, `perPage`) that list endpoints return.
+- Default request timeouts (`timeout`, `open_timeout`) and automatic retries with backoff (`max_retries`, `retry_interval`, `retry_non_idempotent`) on SDK-built connections. Writes are only retried on `429`; `GET`s are also retried on network failures and 502/503/504.
+- `PaystackSdk::TimeoutError` and `PaystackSdk::ConnectionError` wrap transport failures.
+- Connection options are validated and raise `ArgumentError` when invalid or when combined with a pre-built connection.
+
+### Changed
+
+- Faraday constraint relaxed to `>= 2.13, < 3`; added `faraday-retry` dependency.
+
 ## [0.1.0] - 2025-06-26
 
 ### Changed