paystack_sdk 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1161ca83326adeace91da47a17f4c078cee7f6073b4efda0d0d0e707b9744928
-  data.tar.gz: 44a2b6e56897e8e3f020705f2b836f6a6172599f43b1c976144a2cab9165616d
+  metadata.gz: a18abe45774bda30eff6f91a3e93ba55066d9ef4f04ddfc690792edc8b005d94
+  data.tar.gz: 652cc2b936ac3a7211290ad6a6f561d57132fd825588232fab724a0b2378cfa7
 SHA512:
-  metadata.gz: 59fc459f0ca4b103c4815c6523d6a6f6b7bf8088ef391c3d980b829f512aab9e66081796e2713d93d09cfeadb73c6069101ca91ce3b993ccf47389e0d8404df4
-  data.tar.gz: c4cc838ad71d8a8860b037096db5cf3c8cc55ed73a735eb405b4e81bd065a935de1529aa7e31876c64901c3f8fe973c9b2e7294924c7fd36881668a14297056a
+  metadata.gz: 5fcb8324376b91af1c71e894309789fb69a4eeefff5d4a1fa93c190a66c9c01489d5a8a9b4003f8416fbff3ffe5d3474ec6ec49ab9c1a58ed7fb16ebf095c04a
+  data.tar.gz: b094c91f15744f8c02ca9e493d7aa6ab7b9c24f6f0e25cc8e1a94d32bc9d3101aa713a97ff074000e365e1f1857d26735bd99016e82a480b7da839e6be9b349e

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.1.0] - 2025-06-26
+
+### Changed
+
+#### Error Handling Strategy
+
+- **BREAKING**: Clarified error handling approach - the SDK now consistently follows a two-tier error handling strategy:
+  - **Validation errors** (missing/invalid input data) are thrown as exceptions immediately before API calls
+  - **API response errors** (business logic, not found, etc.) are returned as unsuccessful Response objects
+- Updated documentation to clearly explain when exceptions are thrown vs. when to check `response.success?`
+
+#### Test Infrastructure
+
+- **BREAKING**: Standardized all test specifications to use connection doubles instead of Faraday-specific mocks
+- Updated test pattern across all resource specs to use `instance_double("PaystackSdk::Connection")` for better framework independence
+- All tests now follow consistent mocking pattern with `PaystackSdk::Response.new()` expectations
+
+#### Documentation
+
+- Enhanced README with comprehensive error handling examples
+- Added validation error examples showing `MissingParamError`, `InvalidFormatError`, and `InvalidValueError`
+- Updated Quick Start guide to demonstrate proper exception handling
+- Clarified the difference between input validation (exceptions) and API response handling (Response objects)
+
+### Improved
+
+- Better separation of concerns between input validation and API error handling
+- More consistent test suite that's not tied to specific HTTP client implementation
+- Clearer developer experience with predictable error handling patterns
+
+## [0.0.9] - 2025-06-26
+
+### Added
+
+- Verification resource with support for:
+  - Resolving bank accounts
+  - Resolving card BINs
+  - Validating accounts (with required and optional fields)
+- Registered `verification` resource in the main client for easy access
+- Regression tests for all Verification resource methods, including required field validation and full parameter support
+
+### Changed
+
+- Fix the link for listing banks API
+
 ## [0.0.8] - 2025-06-26
 
 ### Added

data/README.md

@@ -69,13 +69,19 @@ params = {
   currency: "NGN"
 }
 
-response = paystack.transactions.initiate(params)
+begin
+  response = paystack.transactions.initiate(params)
 
-if response.success?
-  puts "Visit this URL to complete payment: #{response.authorization_url}"
-  puts "Transaction reference: #{response.reference}"
-else
-  puts "Error: #{response.error_message}"
+  if response.success?
+    puts "Visit this URL to complete payment: #{response.authorization_url}"
+    puts "Transaction reference: #{response.reference}"
+  else
+    puts "Error: #{response.error_message}"
+  end
+rescue PaystackSdk::MissingParamError => e
+  puts "Missing required data: #{e.message}"
+rescue PaystackSdk::InvalidFormatError => e
+  puts "Invalid data format: #{e.message}"
 end
 
 # Create a customer
@@ -85,12 +91,16 @@ customer_params = {
   last_name: "Doe"
 }
 
-customer_response = paystack.customers.create(customer_params)
+begin
+  customer_response = paystack.customers.create(customer_params)
 
-if customer_response.success?
-  puts "Customer created: #{customer_response.data.customer_code}"
-else
-  puts "Error: #{customer_response.error_message}"
+  if customer_response.success?
+    puts "Customer created: #{customer_response.data.customer_code}"
+  else
+    puts "Error: #{customer_response.error_message}"
+  end
+rescue PaystackSdk::ValidationError => e
+  puts "Validation error: #{e.message}"
 end
 ```
 
@@ -98,6 +108,55 @@ end
 
 The SDK handles API responses that use string keys (as returned by Paystack) and provides seamless access through both string and symbol notation. All response data maintains the original string key format from the API while offering convenient dot notation access.
 
+### Error Handling
+
+The SDK uses a two-tier error handling approach:
+
+1. **Validation Errors** (thrown as exceptions) - for missing or invalid input data
+2. **API Response Errors** (returned as unsuccessful Response objects) - for API-level issues
+
+#### Input Validation
+
+The SDK validates your parameters **before** making API calls and throws exceptions immediately for data issues:
+
+```ruby
+begin
+  # This will throw an exception before making any API call
+  response = paystack.transactions.initiate({amount: 1000}) # Missing required email
+rescue PaystackSdk::MissingParamError => e
+  puts "Fix your data: #{e.message}"
+end
+```
+
+#### API Response Handling
+
+All successful API calls return a `Response` object that you can check for success:
+
+```ruby
+response = paystack.transactions.initiate(valid_params)
+
+if response.success?
+  puts "Transaction created: #{response.authorization_url}"
+else
+  puts "Transaction failed: #{response.error_message}"
+
+  # Get detailed error information
+  error_details = response.error_details
+  puts "Status code: #{error_details[:status_code]}"
+  puts "Error message: #{error_details[:message]}"
+end
+```
+
+**Note**: The SDK raises exceptions for:
+
+- **Validation errors** - when required parameters are missing or have invalid formats
+- **Authentication errors** (401) - usually configuration issues
+- **Rate limiting** (429) - requires retry logic
+- **Server errors** (5xx) - Paystack infrastructure issues
+- **Network errors** - connection failures
+
+All other API errors (resource not found, business logic errors, etc.) are returned as unsuccessful Response objects.
+
 ## Usage
 
 ### Client Initialization
@@ -457,19 +516,19 @@ total_count = original.dig("meta", "total")
 current_page = original.dig("meta", "page")
 ```
 
-#### Error Handling
+#### Exception Handling
 
 The SDK provides specific error classes for different types of failures, making it easier to handle errors appropriately:
 
 ```ruby
 begin
   response = paystack.transactions.verify(reference: "invalid_reference")
-rescue PaystackSdk::ResourceNotFoundError => e
-  puts "Resource not found: #{e.message}"
 rescue PaystackSdk::AuthenticationError => e
   puts "Authentication failed: #{e.message}"
-rescue PaystackSdk::ValidationError => e
-  puts "Validation error: #{e.message}"
+rescue PaystackSdk::RateLimitError => e
+  puts "Rate limit exceeded. Retry after: #{e.retry_after} seconds"
+rescue PaystackSdk::ServerError => e
+  puts "Server error: #{e.message}"
 rescue PaystackSdk::APIError => e
   puts "API error: #{e.message}"
 rescue PaystackSdk::Error => e
@@ -507,6 +566,41 @@ The SDK includes several specific error classes:
   - **`PaystackSdk::RateLimitError`** - Rate limiting encountered
   - **`PaystackSdk::ServerError`** - Server errors (5xx responses)
 
+##### Validation Error Examples
+
+The SDK validates your input data **before** making API calls and will throw exceptions immediately if required data is missing or incorrectly formatted:
+
+```ruby
+# Missing required parameter
+begin
+  paystack.transactions.initiate({amount: 1000}) # Missing email
+rescue PaystackSdk::MissingParamError => e
+  puts e.message # => "Missing required parameter: email"
+end
+
+# Invalid format
+begin
+  paystack.transactions.initiate({
+    email: "invalid-email",  # Not a valid email format
+    amount: 1000
+  })
+rescue PaystackSdk::InvalidFormatError => e
+  puts e.message # => "Invalid format for Email. Expected format: valid email address"
+end
+
+# Invalid value
+begin
+  paystack.customers.set_risk_action({
+    customer: "CUS_123",
+    risk_action: "invalid_action"  # Not in allowed values
+  })
+rescue PaystackSdk::InvalidValueError => e
+  puts e.message # => "Invalid value for risk_action: must be one of [default, allow, deny]"
+end
+```
+
+These validation errors are thrown immediately and prevent the API call from being made, helping you catch data issues early in development.
+
 ## Advanced Usage
 
 ### Environment Variables

data/lib/paystack_sdk/client.rb

@@ -5,6 +5,7 @@ require_relative "resources/customers"
 require_relative "resources/transfer_recipients"
 require_relative "resources/transfers"
 require_relative "resources/banks"
+require_relative "resources/verification"
 require_relative "utils/connection_utils"
 
 module PaystackSdk
@@ -106,5 +107,19 @@ module PaystackSdk
     def banks
       @banks ||= Resources::Banks.new(@connection)
     end
+
+    # Provides access to the `Verification` resource.
+    #
+    # @return [PaystackSdk::Resources::Verification] An instance of the
+    #  `Verification` resource.
+    #
+    # @example
+    # ```ruby
+    #   verification = client.verification
+    #   response = verification.resolve_account(account_number: ..., bank_code: ...)
+    # ```
+    def verification
+      @verification ||= Resources::Verification.new(@connection)
+    end
   end
 end

data/lib/paystack_sdk/resources/banks.rb

@@ -4,7 +4,7 @@ module PaystackSdk
   module Resources
     class Banks < Base
       # List banks
-      # @see https://paystack.com/docs/api/bank/#list
+      # @see https://paystack.com/docs/api/miscellaneous/#bank
       def list(query = {})
         if query.key?(:currency)
           validate_allowed_values!(

data/lib/paystack_sdk/resources/verification.rb

@@ -0,0 +1,36 @@
+require_relative "../validations"
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    class Verification < Base
+      # Resolve Bank Account
+      # @see https://paystack.com/docs/api/verification/#resolve-bank-account
+      def resolve_account(account_number:, bank_code:)
+        validate_presence!(value: account_number, name: "account_number")
+        validate_presence!(value: bank_code, name: "bank_code")
+        handle_response(@connection.get("/bank/resolve", {account_number: account_number, bank_code: bank_code}))
+      end
+
+      # Resolve Card BIN
+      # @see https://paystack.com/docs/api/verification/#resolve-card-bin
+      def resolve_card_bin(bin)
+        validate_presence!(value: bin, name: "bin")
+        handle_response(@connection.get("/decision/bin/#{bin}"))
+      end
+
+      # Validate Account
+      # @see https://paystack.com/docs/api/verification/#validate-account
+      # Required: account_number, account_name, account_type, bank_code, country_code, document_type
+      # Optional: document_number
+      def validate_account(params)
+        validate_required_params!(
+          payload: params,
+          required_params: %i[account_number account_name account_type bank_code country_code document_type],
+          operation_name: "Validate Account"
+        )
+        handle_response(@connection.post("/bank/validate", params))
+      end
+    end
+  end
+end

data/lib/paystack_sdk/response.rb

@@ -63,11 +63,11 @@ module PaystackSdk
     # Initializes a new Response object
     #
     # @param response [Faraday::Response, Hash, Array] The raw API response or data
-    # @raise [PaystackSdk::APIError] If the API returns an error response
     # @raise [PaystackSdk::AuthenticationError] If authentication fails (401)
-    # @raise [PaystackSdk::ResourceNotFoundError] If resource is not found (404 or 400 with not found message)
     # @raise [PaystackSdk::RateLimitError] If rate limit is exceeded (429)
     # @raise [PaystackSdk::ServerError] If server returns 5xx error
+    # @note API-level errors (4xx except 401) are returned as unsuccessful Response objects
+    #       rather than raised as exceptions. Use response.success? to check for errors.
     def initialize(response)
       if response.is_a?(Faraday::Response)
         @status_code = response.status
@@ -79,20 +79,25 @@ module PaystackSdk
         case @status_code
         when 200..299
           @success = true
-        when 400
-          handle_400_response
-        when 401
-          raise AuthenticationError.new
-        when 404
-          handle_404_response
+        when 400..499
+          # Client errors - return unsuccessful response for user to handle
+          @success = false
+          @error_message = @api_message || "Client error"
+
+          # Still raise for authentication issues as these are usually config problems
+          if @status_code == 401
+            raise AuthenticationError.new(@api_message || "Authentication failed")
+          end
         when 429
+          # Rate limiting - raise as users need to implement retry logic
           retry_after = response.headers["Retry-After"]
           raise RateLimitError.new(retry_after || 30)
         when 500..599
+          # Server errors - raise as these indicate Paystack infrastructure issues
           raise ServerError.new(@status_code, @api_message)
         else
           @success = false
-          raise APIError.new(@api_message || "Paystack API Error")
+          @error_message = @api_message || "Unknown error"
         end
       elsif response.is_a?(Response)
         @success = response.success?
@@ -120,6 +125,26 @@ module PaystackSdk
       @success
     end
 
+    # Check if the response failed
+    #
+    # @return [Boolean] true if the API request failed
+    def failed?
+      !@success
+    end
+
+    # Get error information if the request failed
+    #
+    # @return [Hash] Hash containing error details, or empty hash if successful
+    def error_details
+      return {} if success?
+
+      {
+        status_code: @status_code,
+        message: @error_message || @api_message,
+        raw_response: @body
+      }.compact
+    end
+
     # Returns the original response body
     # This is useful for debugging or accessing raw data
     #
@@ -284,28 +309,15 @@ module PaystackSdk
       end
     end
 
-    def handle_400_response
-      if @body["code"]&.end_with?("_not_found") ||
-          @api_message&.match?(/not found|cannot find|does not exist/i)
-        resource_type = determine_resource_type
-        meta_info = @body["meta"]&.dig("nextStep")
-        message = @api_message
-        message = "#{message}\nHint: #{meta_info}" if meta_info
-        raise ResourceNotFoundError.new(resource_type, message)
-      else
-        @success = false
-        raise APIError.new(@api_message || "Paystack API Error")
-      end
-    end
+    def determine_resource_type
+      return "Unknown" unless @body.is_a?(Hash) && @body["code"]
 
-    def handle_404_response
-      resource_type = determine_resource_type
-      raise ResourceNotFoundError.new(resource_type, @api_message)
-    end
+      if @body["code"].include?("_")
+        parts = @body["code"].to_s.split("_")
+        return parts.last if parts.last != "not_found"
+      end
 
-    def determine_resource_type
-      resource = @body["code"].split("_").first
-      resource.capitalize
+      "unknown"
     end
   end
 end

data/lib/paystack_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaystackSdk
-  VERSION = "0.0.8"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paystack_sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
 platform: ruby
 authors:
 - Maxwell Nana Forson (theLazyProgrammer)
@@ -121,6 +121,7 @@ files:
 - lib/paystack_sdk/resources/transactions.rb
 - lib/paystack_sdk/resources/transfer_recipients.rb
 - lib/paystack_sdk/resources/transfers.rb
+- lib/paystack_sdk/resources/verification.rb
 - lib/paystack_sdk/response.rb
 - lib/paystack_sdk/utils/connection_utils.rb
 - lib/paystack_sdk/validations.rb