paystack-gateway 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 960e45b01e324553500b07374aa199876b404c5926192a96f52247287dde5c68
-  data.tar.gz: 191204e218673752ccc91c7ea1e08ad43b085e698eebf487bd77cbbce196f6f2
+  metadata.gz: 860924941f63099d74680601ef554e6a8f10f10481381ec04316dec8ea37bff8
+  data.tar.gz: 9c74c683a3612bd75d8f03ec2cc2ad4a0d18ec078e085c9693862b1e4eb3bf23
 SHA512:
-  metadata.gz: ab9e8ad8ed05816b07dc34e67099f80109f4ec20ae34b39ab3905c7b1bcb32fb5278913ffa5e6e85ac4486ca8417208849a091fff828e04eeed282227f19e704
-  data.tar.gz: 8bb3746cc29c83352555a60567193c1e8a82b99711681e9730325e25279341b4d30e9724b4fdd54bf9e63e300418d1ee4f767474afa5c23c0f68c54492dbb384
+  metadata.gz: ae2df9306e0b22b880347d442e7e7a9bbbc3c76a885f830371022a8cc32a17cd300bbe0619fabee14ab5a674cfd4f8c23c51781081ac82855685fe0feb1184f1
+  data.tar.gz: e24f66f685989b6867eb4ca409dc656d853ccf876a6f83f3665828da152227f93dfde8cdc96e19a7c8fc214c9886fff8dc0a08933b853b33748553cd42ab19d0

data/.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   - rubocop-minitest
   - rubocop-rake
 
@@ -6,10 +6,20 @@ AllCops:
   TargetRubyVersion: 3.3
   NewCops: enable
 
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented_relative_to_receiver
 Metrics/AbcSize:
-  Max: 25
+  Max: 28
+Metrics/CyclomaticComplexity:
+  Max: 10
 Metrics/MethodLength:
   Max: 25
+Metrics/ModuleLength:
+  Max: 250
+Metrics/ParameterLists:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Max: 10
 Minitest/MultipleAssertions:
   Enabled: false
 Naming/FileName:

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-04
+
+### Added
+
+- Generate API modules, methods, response classes, and errors from Paystack's
+  OpenAPI specification.
+- Cover 163 generated operations across 27 API groups, including Direct Debit
+  and Virtual Terminal.
+- Add opt-out response and error extensions for common transaction, transfer,
+  refund, customer, and plan workflows.
+- Generate per-operation happy-path VCR tests for response-class selection and
+  response data parsing, with recording inputs directly in each test.
+- Add 126 successful canonical endpoint recordings and document prerequisites
+  for 37 intentionally skipped endpoint tests.
+- Add isolated regression tests for DELETE request bodies.
+
+### Changed
+
+- Update the Paystack OpenAPI submodule to `07c5abc` and generate from its
+  bundled `dist/paystack.yaml` specification.
+- Prefer the generated singular API modules while retaining the original plural
+  modules as deprecated, backwards-compatible entry points.
+- Organize deprecated implementations under `paystack_gateway/legacy` while
+  preserving their original require paths.
+- Log full failed-response details at debug level and use lazy logger blocks.
+- Preserve manually maintained API tests when regenerating the SDK.
+
+### Fixed
+
+- Include path-item parameters when generating method signatures and URLs.
+- Preserve OpenAPI enum options and Ruby-style keyword names in generated API
+  documentation.
+- Treat request properties as optional unless the OpenAPI schema marks them as
+  required.
+- Support top-level array request bodies such as bulk charges.
+- Preserve the legacy `Miscellaneous.list_banks` API across regeneration.
+- Apply refund extensions to the generated refund response classes.
+- Keep decorated API methods compatible with temporary method stubs.
+- Correct the generated customer fetch endpoint and camel-cased request keys.
+- Send DELETE request-body properties as JSON rather than query parameters.
+- Handle string and missing API error response bodies safely.
+
+## [0.1.1] - 2025-01-24
+
+### Fixed
+
+- Correct the dedicated virtual account requery endpoint.
+- Recognize subclasses of Faraday connection errors as network errors.
+- Handle non-JSON request bodies and optional log filtering more gracefully.
+- Defer API method decoration until all API modules are loaded.
+- Correct the gem's placeholder name.
+
 ## [0.1.0] - 2024-10-27
 
 - Initial release
+
+[Unreleased]: https://github.com/darthrighteous/paystack-gateway/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/darthrighteous/paystack-gateway/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/darthrighteous/paystack-gateway/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/darthrighteous/paystack-gateway/releases/tag/v0.1.0

data/README.md

@@ -21,9 +21,10 @@ To use the PaystackGateway gem, you need to configure it with your Paystack secr
 
 The configuration options are
 - `secret_key`: Your paystack api key used to authorize requests
-- `logger`: Your ruby Logger. Default is Logger.new($stdout)
+- `logger`: Your ruby Logger. Default is `Logger.new($stdout)`
 - `logging_options`:  Options passed to [Faraday logger middleware](https://github.com/lostisland/faraday/blob/main/lib/faraday/response/logger.rb). Default is `{ headers: false }`
 - `log_filter`: Filter used when logging headers and body.
+- `use_extensions`: Enable extension modules that add useful helper methods to response and error objects. Default is `true`.
 
 ```ruby
 # config/initializers/paystack_gateway.rb
@@ -41,30 +42,78 @@ end
 
 ## Usage
 
-### Calling API endpoints
-Once configured, you can start using the various API modules and methods provided by the gem. They are designed to mirror how the api methods are grouped and listed on the [Paystack API](https://paystack.com/docs/api/).
+Once configured, you can begin utilising the various API modules and methods provided by the gem.
+```irb
+:001 > r = PaystackGateway::Customer.fetch(code: 'test@example.com')
+  I, [2025-03-30T19:53:06.951015 #29623]  INFO -- : request: GET https://api.paystack.co/customer/test@example.com
+  I, [2025-03-30T19:53:07.486206 #29623]  INFO -- : response: Status 200
+  =>
+  {:status=>true,
+  ...
+:002 > r.class
+ => PaystackGateway::Customer::FetchResponse
+:003 > r.customer_code
+  => "CUS_xsrozmbt8g1oear"
+```
 
-Here's an example creating a customer using the [/customer/create endpoint](https://paystack.com/docs/api/customer/#create).
+### API Organisation
 
-```ruby
-response = PaystackGateway::Customers.create_customer(
-  email: 'test@example.com',
-  first_name: 'Test',
-  last_name: 'User',
-)
+The code is generated directly from [Paystack's OpenAPI specification](https://github.com/PaystackOSS/openapi), ensuring that it mirrors Paystack’s API organisation accurately. Refer to the API documentation for detailed schemas and available options for each endpoint.
+
+- **API Modules**: Each API tag in the Paystack documentation becomes a module under `PaystackGateway`. For example, the Transaction API is accessible via `PaystackGateway::Transaction`.
+- **API Methods**: Each operation within a tag is implemented as a method in the corresponding module. For instance, to verify a transaction, you call `PaystackGateway::Transaction.verify`.
+
+### Parameters
+
+All API parameters are implemented as method arguments:
+
+- **Path parameters**: Required parameters in the URL path (e.g., `reference` in `/transaction/verify/{reference}`)
+- **Query parameters**: Optional parameters for GET requests (e.g., `from`, `to` in `/transaction/totals`)
+- **Request body parameters**: Parameters sent in the request body for POST/PUT requests
+
+Required parameters are clearly marked in the method signatures, while optional parameters typically default to `nil`.
+
+### Responses
+
+Each API method returns a specific response object. For example, when you call `PaystackGateway::Transaction.verify`, you will receive either:
+
+- `PaystackGateway::Transaction::VerifyResponse`, which indicates a successful call.
+- `PaystackGateway::Transaction::VerifyError`, which is raised if the call fails.
+
+Paystack responses usually include the main payload nested in the `data` field of the response body. To simplify access, the response objects automatically delegate known attributes from this field, allowing you to reference them directly.
+
+For instance, here’s how you can fetch a customer using the [/customer/{code} endpoint](https://paystack.com/docs/api/customer/#fetch):
 
+
+```ruby
+response = PaystackGateway::Customer.fetch(code: 'CUS_xsrozmbt8g1oear')
+
+# An example of the original response body:
+# {:status=>true,
+#  :message=>"Customer retrieved",
+#  :data=>
+#   {"email"=>"test@example.com",
+#    "phone"=>"+2348011111111",
+#    "customer_code"=>"CUS_xsrozmbt8g1oear",
+#    "id"=>203316808,
+#    ...
+
+# You can access the attributes directly:
 response.id # => 203316808
 response.customer_code # => "CUS_xsrozmbt8g1oear"
+
+# Alternatively, you can access them via the data field:
+response.data.id # => 203316808
+response.data.customer_code # => "CUS_xsrozmbt8g1oear"
 ```
 
 ### Error Handling
-Whenever a network error occurs or the called endpoint responds with an error response, a `PaystackGateway::ApiError`(or a subclass of it) is raised that can be handled in your calling code.
 
-Here's an example initializing a transaction using the [/transaction/initialize endpoint](https://paystack.com/docs/api/transaction/#initialize)
+Whenever a network error occurs or the called endpoint returns an error response, a `PaystackGateway::ApiError` (or one of its subclasses) is raised, which you can handle in your code. For example, initialising a transaction using the [/transaction/initialize endpoint](https://paystack.com/docs/api/transaction/#initialize) might be done as follows:
 
 ```ruby
 begin
-  response = PaystackGateway::Transactions.initialize_transaction(
+  response = PaystackGateway::Transaction.initialize_transaction(
     email: 'test@example.com',
     amount: 1000,
     reference: 'test_reference',
@@ -87,91 +136,21 @@ Some endpoints currently make use of caching:
 - Miscellaneous#list_banks
 - Verifications#resolve_account_number
 
-Caching works using an [ActiveSupport::Cache::FileStore](https://api.rubyonrails.org/classes/ActiveSupport/Cache/FileStore.html) cache. The default caching period is 7 days and the cache data is stored on the file system at `ENV['TMPDIR']` or `/tmp/cache`. 
-
-
-## API Modules and Methods
-> Refer to the [Paystack API documentation](https://paystack.com/docs/api) for details on all the available endpoints and their usage.
-
-### Implemented Modules and Methods
-
-Below is a complete list of the API modules and methods that are currently implemented.
-
-I invite you to collaborate on this project! If you need to use any of the unimplemented API methods or modules, or if you want to make modifications to the defaults or the level of configuration available in the currently implemented API methods, please feel free to raise a pull request (PR). See [Contributing](#contributing) and [Code of Conduct](#code-of-conduct) below
-
-- [x] [Transactions](https://paystack.com/docs/api/transaction/)
-  - [x] [Initialize Transaction](https://paystack.com/docs/api/transaction/#initialize)
-  - [x] [Verify Transaction](https://paystack.com/docs/api/transaction/#verify)
-  - [ ] [List Transactions](https://paystack.com/docs/api/transaction/#list)
-  - [ ] [Fetch Transaction](https://paystack.com/docs/api/transaction/#fetch)
-  - [x] [Charge Authorization](https://paystack.com/docs/api/transaction/#charge-authorization)
-  - [ ] [View Transaction Timeline](https://paystack.com/docs/api/transaction/#view-timeline)
-  - [ ] [Transaction Totals](https://paystack.com/docs/api/transaction/#totals)
-  - [ ] [Export Transactions](https://paystack.com/docs/api/transaction/#export)
-  - [ ] [Partial Debit](https://paystack.com/docs/api/transaction/#partial-debit)
-
-- [ ] [Customers](https://paystack.com/docs/api/customer/)
-  - [x] [Create Customer](https://paystack.com/docs/api/customer/#create)
-  - [ ] [List Customers](https://paystack.com/docs/api/customer/#list)
-  - [x] [Fetch Customer](https://paystack.com/docs/api/customer/#fetch)
-  - [ ] [Update Customer](https://paystack.com/docs/api/customer/#update)
-  - [ ] [Validate Customer](https://paystack.com/docs/api/customer/#validate)
-  - [ ] [Whitelist/Blacklist Customer](https://paystack.com/docs/api/customer/#whitelist-blacklist)
-  - [ ] [Deactivate Authorization](https://paystack.com/docs/api/customer/#deactivate-authorization)
-
-- [x] [Dedicated Virtual Accounts](https://paystack.com/docs/api/dedicated-virtual-account/)
-  - [x] [Create Dedicated Virtual Account](https://paystack.com/docs/api/dedicated-virtual-account/#create)
-  - [x] [Assign Dedicated Virtual Account](https://paystack.com/docs/api/dedicated-virtual-account/#assign)
-  - [ ] [List Dedicated Accounts](https://paystack.com/docs/api/dedicated-virtual-account/#list)
-  - [ ] [Fetch Dedicated Account](https://paystack.com/docs/api/dedicated-virtual-account/#fetch)
-  - [x] [Requery Dedicated Account](https://paystack.com/docs/api/dedicated-virtual-account/#requery)
-  - [ ] [Deactivate Dedicated Account](https://paystack.com/docs/api/dedicated-virtual-account/#deactivate)
-  - [x] [Split Dedicated Account Transaction](https://paystack.com/docs/api/dedicated-virtual-account/#add-split)
-  - [ ] [Remove Split from Dedicated Account](https://paystack.com/docs/api/dedicated-virtual-account/#remove-split)
-  - [ ] [Fetch Bank Providers](https://paystack.com/docs/api/dedicated-virtual-account/#providers)
-
-- [ ] [Subaccounts](https://paystack.com/docs/api/subaccount/)
-  - [x] [Create Subaccount](https://paystack.com/docs/api/subaccount/#create)
-  - [ ] [List Subaccounts](https://paystack.com/docs/api/subaccount/#list)
-  - [ ] [Fetch Subaccount](https://paystack.com/docs/api/subaccount/#fetch)
-  - [x] [Update Subaccount](https://paystack.com/docs/api/subaccount/#update)
-
-- [x] [Plans](https://paystack.com/docs/api/plan/)
-  - [x] [Create Plan](https://paystack.com/docs/api/plan/#create)
-  - [x] [List Plans](https://paystack.com/docs/api/plan/#list)
-  - [x] [Fetch Plan](https://paystack.com/docs/api/plan/#fetch)
-  - [x] [Update Plan](https://paystack.com/docs/api/plan/#update)
-
-- [x] [Transfer Recipients](https://paystack.com/docs/api/transfer-recipient/)
-  - [x] [Create Transfer Recipient](https://paystack.com/docs/api/transfer-recipient/#create)
-  - [ ] [Bulk Create Transfer Recipient](https://paystack.com/docs/api/transfer-recipient/#bulk)
-  - [ ] [List Transfer Recipients](https://paystack.com/docs/api/transfer-recipient/#list)
-  - [ ] [Fetch Transfer Recipient](https://paystack.com/docs/api/transfer-recipient/#fetch)
-  - [ ] [Update Transfer Recipient](https://paystack.com/docs/api/transfer-recipient/#update)
-  - [ ] [Delete Transfer Recipient](https://paystack.com/docs/api/transfer-recipient/#delete)
-
-- [x] [Transfers](https://paystack.com/docs/api/transfer/)
-  - [x] [Initiate Transfer](https://paystack.com/docs/api/transfer/#initiate)
-  - [ ] [Finalize Transfer](https://paystack.com/docs/api/transfer/#finalize)
-  - [ ] [Initiate Bulk Transfer](https://paystack.com/docs/api/transfer/#bulk)
-  - [ ] [List Transfers](https://paystack.com/docs/api/transfer/#list)
-  - [ ] [Fetch Transfer](https://paystack.com/docs/api/transfer/#fetch)
-  - [x] [Verify Transfer](https://paystack.com/docs/api/transfer/#verify)
-
-- [x] [Refunds](https://paystack.com/docs/api/refund/)
-  - [x] [Create Refund](https://paystack.com/docs/api/refund/#create)
-  - [x] [List Refunds](https://paystack.com/docs/api/refund/#list)
-  - [x] [Fetch Refund](https://paystack.com/docs/api/refund/#fetch)
-
-- [x] [Verification](https://paystack.com/docs/api/verification/)
-  - [x] [Resolve Account Number](https://paystack.com/docs/api/verification/#resolve-account)
-  - [ ] [Validate Account](https://paystack.com/docs/api/verification/#validate-account)
-  - [ ] [Resolve Card BIN](https://paystack.com/docs/api/verification/#resolve-card)
-
-- [x] [Miscellaneous](https://paystack.com/docs/api/miscellaneous/)
-  - [x] [List Banks](https://paystack.com/docs/api/miscellaneous/#bank)
-  - [ ] [List/Search Countries](https://paystack.com/docs/api/miscellaneous/#country)
-  - [ ] [List States (AVS)](https://paystack.com/docs/api/miscellaneous/#avs-states)
+Caching works using an [ActiveSupport::Cache::FileStore](https://api.rubyonrails.org/classes/ActiveSupport/Cache/FileStore.html) cache. The default caching period is 7 days and the cache data is stored on the file system at `ENV['TMPDIR']` or `/tmp/cache`.
+
+### Extensions
+
+PaystackGateway includes extension modules that offer additional helper methods on both response and error objects. These modules are enabled by default, so you can immediately benefit from simpler data access and enhanced error handling.
+
+If you prefer to opt out of these enhancements, you can update your configuration as follows:
+
+```ruby
+PaystackGateway.configure do |config|
+  config.use_extensions = false
+end
+```
+
+For additional details on the available extensions and helper methods, please refer directly to the source code in the [extensions directory](https://github.com/darthrighteous/paystack-gateway/tree/main/lib/paystack_gateway/extensions).
 
 
 ## Development
@@ -184,7 +163,7 @@ I invite you to collaborate on this project! If you need to use any of the unimp
 
 ### Setting up
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ### Running the tests and linter
 
@@ -193,9 +172,9 @@ Minitest is used for unit tests. Rubocop is used to enforce the ruby style.
 To run the complete set of tests and linter run the following:
 
 ```bash
-$ bundle install
-$ bundle exec rake test
-$ bundle exec rubocop
+$ bin/setup
+$ bin/test
+$ bin/lint
 ```
 
 ## Contributing

data/lib/paystack_gateway/api_error.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'faraday/error'
+require 'active_support/core_ext/hash/indifferent_access'
 
 module PaystackGateway
   # This error is raised when an exception occurs in the process of fulfilling
@@ -72,6 +73,7 @@ module PaystackGateway
     private
 
     def http_code = original_error.try(:response_status)
-    def response_body = original_error.try(:response_body)&.with_indifferent_access
+    def original_response_body = original_error.try(:response_body)
+    def parsed_response_body = original_response_body.try(:with_indifferent_access) || {}
   end
 end

data/lib/paystack_gateway/apple_pay.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/applepay
+  #
+  # Apple Pay
+  # A collection of endpoints for managing application's top-level domain or subdomain accepting payment via Apple Pay
+  module ApplePay
+    include PaystackGateway::RequestModule
+
+    # Successful response from calling #list_domain.
+    class ListDomainResponse < PaystackGateway::Response; end
+
+    # Error response from #list_domain.
+    class ListDomainError < ApiError; end
+
+    # https://paystack.com/docs/api/apple-pay/#list_domain
+    # List Domains: GET /apple-pay/domain
+    # Lists all registered domains on your integration. Returns an empty array if no domains
+    # have been added.
+    #
+    # @param use_cursor [Boolean]
+    #        A flag to indicate if cursor based pagination should be used
+    # @param next [String]
+    #        An alphanumeric value returned for every cursor based retrieval, used to retrieve
+    #        the next set of data
+    # @param previous [String]
+    #        An alphanumeric value returned for every cursor based retrieval, used to retrieve
+    #        the previous set of data
+    #
+    # @return [ListDomainResponse] successful response
+    # @raise [ListDomainError] if the request fails
+    api_method def self.list_domain(use_cursor: nil, next: nil, previous: nil)
+      use_connection do |connection|
+        connection.get(
+          '/apple-pay/domain',
+          { use_cursor:, next:, previous: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #register_domain.
+    class RegisterDomainResponse < PaystackGateway::Response; end
+
+    # Error response from #register_domain.
+    class RegisterDomainError < ApiError; end
+
+    # https://paystack.com/docs/api/apple-pay/#register_domain
+    # Register Domain: POST /apple-pay/domain
+    # Register a top-level domain or subdomain for your Apple Pay integration. > This
+    # endpoint can only be called with one domain or subdomain at a time.
+    #
+    # @param domain_name [String] (required)
+    #        The domain or subdomain for your application
+    #
+    # @return [RegisterDomainResponse] successful response
+    # @raise [RegisterDomainError] if the request fails
+    api_method def self.register_domain(domain_name:)
+      use_connection do |connection|
+        connection.post(
+          '/apple-pay/domain',
+          { domainName: domain_name }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #unregister_domain.
+    class UnregisterDomainResponse < PaystackGateway::Response; end
+
+    # Error response from #unregister_domain.
+    class UnregisterDomainError < ApiError; end
+
+    # https://paystack.com/docs/api/apple-pay/#unregister_domain
+    # Unregister Domain: DELETE /apple-pay/domain
+    # Unregister a top-level domain or subdomain previously used for your Apple Pay integration.
+    #
+    # @param domain_name [String] (required)
+    #        The domain or subdomain for your application
+    #
+    # @return [UnregisterDomainResponse] successful response
+    # @raise [UnregisterDomainError] if the request fails
+    api_method def self.unregister_domain(domain_name:)
+      use_connection do |connection|
+        connection.delete(
+          '/apple-pay/domain',
+        ) do |request|
+          request.body = { domainName: domain_name }.compact
+        end
+      end
+    end
+  end
+end

data/lib/paystack_gateway/balance.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/balance
+  #
+  # Balance
+  # A collection of endpoints gaining insights into the amount on an integration
+  module Balance
+    include PaystackGateway::RequestModule
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response; end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/balance/#fetch
+    # Fetch Balance: GET /balance
+    # Fetch the available balance on your integration
+    #
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch
+      use_connection do |connection|
+        connection.get(
+          '/balance',
+        )
+      end
+    end
+
+    # Successful response from calling #ledger.
+    class LedgerResponse < PaystackGateway::Response; end
+
+    # Error response from #ledger.
+    class LedgerError < ApiError; end
+
+    # https://paystack.com/docs/api/balance/#ledger
+    # Balance Ledger: GET /balance/ledger
+    # Fetch all pay-ins and pay-outs that occured on your integration
+    #
+    # @param per_page [Integer]
+    #        Number of records to fetch per page
+    # @param page [Integer]
+    #        The section to retrieve
+    # @param from [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    #
+    # @return [LedgerResponse] successful response
+    # @raise [LedgerError] if the request fails
+    api_method def self.ledger(per_page: nil, page: nil, from: nil, to: nil)
+      use_connection do |connection|
+        connection.get(
+          '/balance/ledger',
+          { perPage: per_page, page:, from:, to: }.compact,
+        )
+      end
+    end
+  end
+end