paystack_sdk 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dc8af5f5a8c1305ac52bb936f3601982204a1ccab20ee7d63b2b7ad89c03b3f
-  data.tar.gz: 30c6c8e89a107566d079ca22f78f56cbb6d48701db2d97f60ddb6357a2f5c5b7
+  metadata.gz: d4ff6401efb6a0aba25394b61aa74e1a2645848c015565f3590ffdc10f504748
+  data.tar.gz: e59175c14b106866b7129e5cb640ec9a64feebb5a2ddce12940e0436e8dc88af
 SHA512:
-  metadata.gz: b5f448b8d57b73b3837542791f56418b1711dc697b7551b1240eac3b86d5337d7a125b70d006654ef41a84e16b40da38ad5bb5178faf50fee12ac72ca9d8c7f1
-  data.tar.gz: 6c3d0d9eb5c06106e1fea26e7434034a42693925cae29a7cbf9288d5655c48598a91a80cc353b238dfdd9bb73be957d4f2e511fc54004260521aa8fedaf17cf3
+  metadata.gz: 964956e0a22d4ea337ac49896a865d43a0d6ba6ac2f2cc307a49f120b0b407cb4dedf80c6f3b5ed8a227b89d283e5a9d2729210c3763d4f6236f373de5e9bc6b
+  data.tar.gz: e86ef5b41b26ee645f3f3b208cc945cb382d38d768ace5440af66fc0e82a3fac2e036902723021da0d896b90b4b1877b5f395f3ea2860e577010035624608de7

data/.standard.yml

@@ -1,5 +1,5 @@
 # For available configuration options, see:
 #   https://github.com/standardrb/standard
-ruby_version: 3.2.2
+ruby_version: 3.3.5
 fix: true
-format: progress
+format: progress

data/CHANGELOG.md

@@ -1,5 +1,88 @@
-## [Unreleased]
+# Changelog
+
+## [0.0.6] - 2025-06-10
+
+### Added
+
+- Customers resource with full CRUD operations (create, list, fetch, update)
+- Customer validation and risk action management features
+- Customer authorization deactivation functionality
+- Comprehensive documentation for Customers API in README
+
+### Changed
+
+- Improved test consistency by standardizing response body format using string keys with hashrocket notation (`=>`) across all test specifications
+- Enhanced error handling specificity in tests by using appropriate error classes (`InvalidValueError`, `InvalidFormatError`, `MissingParamError`) instead of generic `Error` class
+
+### Improved
+
+- Better test coverage and reliability with consistent response format handling
+- More precise error validation ensuring proper exception types are raised for different validation failures
+- Enhanced documentation with comprehensive examples for all customer operations
+
+## [0.0.5] - 2025-05-15
+
+### Added
+
+- Connection utilities module for improved API connection handling and management
+- Enhanced connection configuration and error handling capabilities
+
+## [0.0.4] - 2025-05-15
+
+### Added
+
+- Enhanced transaction resource validations with comprehensive parameter checking
+- New transaction methods: `charge_authorization` and `partial_debit`
+- Flexible `list` method accepting additional parameters for advanced API requests
+
+### Changed
+
+- Updated SDK authentication to use `secret_key` instead of `api_key` for consistency with Paystack documentation
+- Improved transaction method names for better clarity and consistency
+- Enhanced README documentation with comprehensive usage examples
+
+### Improved
+
+- Better validation error messages and handling
+- More robust parameter validation across all transaction methods
+
+## [0.0.3] - 2025-05-13
+
+### Changed
+
+- Renamed `#initialize_transaction` method to `#initiate` for better clarity and consistency with Paystack API
+- Updated .gitignore to exclude Gemfile.lock from version control
+
+### Fixed
+
+- Corrected typos in README documentation regarding original API response handling
+
+## [0.0.2] - 2025-05-11
+
+### Added
+
+- Comprehensive Response class for Paystack API response handling with dynamic attribute access
+- Enhanced response object capabilities with better data access patterns
+- Improved debugging support for development
+
+### Changed
+
+- Refactored transaction specs to utilize PaystackSdk::Response for better consistency
+- Removed redundant success? method in favor of centralized Response handling
+- Enhanced documentation clarity on original API response handling
+
+### Improved
+
+- Better response handling architecture across all SDK components
+- More intuitive API for accessing response data and metadata
 
 ## [0.0.1] - 2025-05-10
 
-- Initial release
+### Added
+
+- Initial release of Paystack Ruby SDK
+- Basic transaction operations (initiate, verify)
+- Foundational SDK architecture with modular design
+- Comprehensive error handling framework
+- Basic client initialization and configuration
+- Initial documentation and usage examples

data/README.md

@@ -14,6 +14,14 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
     - [List Transactions](#list-transactions)
     - [Fetch a Transaction](#fetch-a-transaction)
     - [Get Transaction Totals](#get-transaction-totals)
+  - [Customers](#customers)
+    - [Create a Customer](#create-a-customer)
+    - [List Customers](#list-customers)
+    - [Fetch a Customer](#fetch-a-customer)
+    - [Update a Customer](#update-a-customer)
+    - [Validate a Customer](#validate-a-customer)
+    - [Set Risk Action](#set-risk-action)
+    - [Deactivate Authorization](#deactivate-authorization)
   - [Response Handling](#response-handling)
     - [Working with Response Objects](#working-with-response-objects)
     - [Accessing the Original Response](#accessing-the-original-response)
@@ -65,11 +73,31 @@ 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}"
 end
+
+# Create a customer
+customer_params = {
+  email: "customer@email.com",
+  first_name: "John",
+  last_name: "Doe"
+}
+
+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}"
+end
 ```
 
+### Response Format
+
+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.
+
 ## Usage
 
 ### Client Initialization
@@ -219,6 +247,165 @@ else
 end
 ```
 
+### Customers
+
+The SDK provides comprehensive support for Paystack's Customer API, allowing you to manage customer records and their associated data.
+
+#### Create a Customer
+
+```ruby
+# Prepare customer parameters
+params = {
+  email: "customer@example.com",
+  first_name: "John",
+  last_name: "Doe",
+  phone: "+2348123456789"
+}
+
+# Create the customer
+response = paystack.customers.create(params)
+
+if response.success?
+  puts "Customer created successfully!"
+  puts "Customer Code: #{response.data.customer_code}"
+  puts "Email: #{response.data.email}"
+  puts "Name: #{response.data.first_name} #{response.data.last_name}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### List Customers
+
+```ruby
+# Get all customers (default pagination: 50 per page)
+response = paystack.customers.list
+
+# With custom pagination
+response = paystack.customers.list(per_page: 20, page: 2)
+
+# With date filters
+response = paystack.customers.list(
+  per_page: 10,
+  page: 1,
+  from: "2025-01-01",
+  to: "2025-06-10"
+)
+
+if response.success?
+  puts "Total customers: #{response.data.size}"
+
+  response.data.each do |customer|
+    puts "Code: #{customer.customer_code}"
+    puts "Email: #{customer.email}"
+    puts "Name: #{customer.first_name} #{customer.last_name}"
+    puts "----------------"
+  end
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### Fetch a Customer
+
+```ruby
+# Fetch by customer code
+customer_code = "CUS_xr58yrr2ujlft9k"
+response = paystack.customers.fetch(customer_code)
+
+# Or fetch by email
+response = paystack.customers.fetch("customer@example.com")
+
+if response.success?
+  customer = response.data
+  puts "Customer details:"
+  puts "Code: #{customer.customer_code}"
+  puts "Email: #{customer.email}"
+  puts "Name: #{customer.first_name} #{customer.last_name}"
+  puts "Phone: #{customer.phone}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### Update a Customer
+
+```ruby
+customer_code = "CUS_xr58yrr2ujlft9k"
+update_params = {
+  first_name: "Jane",
+  last_name: "Smith",
+  phone: "+2348987654321"
+}
+
+response = paystack.customers.update(customer_code, update_params)
+
+if response.success?
+  puts "Customer updated successfully!"
+  puts "Updated Name: #{response.data.first_name} #{response.data.last_name}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### Validate a Customer
+
+```ruby
+customer_code = "CUS_xr58yrr2ujlft9k"
+validation_params = {
+  country: "NG",
+  type: "bank_account",
+  account_number: "0123456789",
+  bvn: "20012345677",
+  bank_code: "007",
+  first_name: "John",
+  last_name: "Doe"
+}
+
+response = paystack.customers.validate(customer_code, validation_params)
+
+if response.success?
+  puts "Customer validation initiated: #{response.message}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### Set Risk Action
+
+```ruby
+params = {
+  customer: "CUS_xr58yrr2ujlft9k",
+  risk_action: "allow"  # Options: "default", "allow", "deny"
+}
+
+response = paystack.customers.set_risk_action(params)
+
+if response.success?
+  puts "Risk action set successfully!"
+  puts "Customer: #{response.data.customer_code}"
+  puts "Risk Action: #{response.data.risk_action}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### Deactivate Authorization
+
+```ruby
+params = {
+  authorization_code: "AUTH_72btv547"
+}
+
+response = paystack.customers.deactivate_authorization(params)
+
+if response.success?
+  puts "Authorization deactivated: #{response.message}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
 ### Response Handling
 
 #### Working with Response Objects
@@ -272,7 +459,24 @@ current_page = original.dig("meta", "page")
 
 #### Error 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::APIError => e
+  puts "API error: #{e.message}"
+rescue PaystackSdk::Error => e
+  puts "General error: #{e.message}"
+end
+
+# Alternatively, check response success without exceptions
 response = paystack.transactions.verify(reference: "invalid_reference")
 
 unless response.success?
@@ -287,6 +491,22 @@ unless response.success?
 end
 ```
 
+##### Error Types
+
+The SDK includes several specific error classes:
+
+- **`PaystackSdk::ValidationError`** - Base class for all validation errors
+
+  - **`PaystackSdk::MissingParamError`** - Raised when required parameters are missing
+  - **`PaystackSdk::InvalidFormatError`** - Raised when parameters have invalid format (e.g., invalid email)
+  - **`PaystackSdk::InvalidValueError`** - Raised when parameters have invalid values (e.g., not in allowed list)
+
+- **`PaystackSdk::APIError`** - Base class for API-related errors
+  - **`PaystackSdk::AuthenticationError`** - Authentication failures
+  - **`PaystackSdk::ResourceNotFoundError`** - Resource not found (404 errors)
+  - **`PaystackSdk::RateLimitError`** - Rate limiting encountered
+  - **`PaystackSdk::ServerError`** - Server errors (5xx responses)
+
 ## Advanced Usage
 
 ### Environment Variables
@@ -299,6 +519,7 @@ ENV["PAYSTACK_SECRET_KEY"] = "sk_test_xxx"
 
 # Then initialize resources without specifying the key
 transactions = PaystackSdk::Resources::Transactions.new
+customers = PaystackSdk::Resources::Customers.new
 ```
 
 ### Direct Resource Instantiation
@@ -308,6 +529,7 @@ For more advanced usage, you can instantiate resource classes directly:
 ```ruby
 # With a secret key
 transactions = PaystackSdk::Resources::Transactions.new(secret_key: "sk_test_xxx")
+customers = PaystackSdk::Resources::Customers.new(secret_key: "sk_test_xxx")
 
 # With an existing Faraday connection
 connection = Faraday.new(url: "https://api.paystack.co") do |conn|
@@ -316,6 +538,7 @@ end
 
 # The secret key can be omitted if set in an environment
 transactions = PaystackSdk::Resources::Transactions.new(connection, secret_key:)
+customers = PaystackSdk::Resources::Customers.new(connection, secret_key:)
 ```
 
 For more detailed documentation on specific resources, please refer to the following guides:
@@ -329,6 +552,33 @@ For more detailed documentation on specific resources, please refer to the follo
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Testing
+
+The SDK includes comprehensive test coverage with consistent response format handling. All test specifications use string keys with hashrocket notation (`=>`) to match the actual format returned by the Paystack API:
+
+```ruby
+# Example test response format
+.and_return(Faraday::Response.new(status: 200, body: {
+  "status" => true,
+  "message" => "Transaction initialized",
+  "data" => {
+    "authorization_url" => "https://checkout.paystack.com/abc123",
+    "access_code" => "access_code_123",
+    "reference" => "ref_123"
+  }
+}))
+```
+
+Tests also validate specific error types to ensure proper exception handling:
+
+```ruby
+# Testing specific error types
+expect { customers.set_risk_action(invalid_params) }
+  .to raise_error(PaystackSdk::InvalidValueError, /risk_action/i)
+```
+
+### Installation and Release
+
 To install this gem onto your local machine, run:
 
 ```bash

data/lib/paystack_sdk/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "resources/transactions"
+require_relative "resources/customers"
 require_relative "utils/connection_utils"
 
 module PaystackSdk
@@ -46,5 +47,19 @@ module PaystackSdk
     def transactions
       @transactions ||= Resources::Transactions.new(@connection)
     end
+
+    # Provides access to the `Customers` resource.
+    #
+    # @return [PaystackSdk::Resources::Customers] An instance of the
+    #  `Customers` resource.
+    #
+    # @example
+    # ```ruby
+    #   customers = client.customers
+    #   response = customers.list
+    # ```
+    def customers
+      @customers ||= Resources::Customers.new(@connection)
+    end
   end
 end

data/lib/paystack_sdk/resources/customers.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # The `Customers` class provides methods for interacting with the Paystack Customers API.
+    # It allows you to create, list, fetch, update, and manage customers on your integration.
+    #
+    # Example usage:
+    # ```ruby
+    #   customers = PaystackSdk::Resources::Customers.new(secret_key:)
+    #
+    #   # Create a customer
+    #   payload = { email: "customer@email.com", first_name: "Zero", last_name: "Sum" }
+    #   response = customers.create(payload)
+    #   if response.success?
+    #     puts "Customer created successfully."
+    #     puts "Customer code: #{response.customer_code}"
+    #   else
+    #     puts "Error creating customer: #{response.error_message}"
+    #   end
+    #
+    #   # List customers
+    #   response = customers.list(per_page: 50, page: 1)
+    #
+    #   # Fetch a customer
+    #   response = customers.fetch("CUS_xxxxx")
+    #
+    #   # Update a customer
+    #   response = customers.update("CUS_xxxxx", { first_name: "John" })
+    # ```
+    class Customers < PaystackSdk::Resources::Base
+      # Creates a new customer.
+      #
+      # @param payload [Hash] The payload containing customer details.
+      # @option payload [String] :email (required) Customer's email address
+      # @option payload [String] :first_name Customer's first name
+      # @option payload [String] :last_name Customer's last name
+      # @option payload [String] :phone Customer's phone number
+      # @option payload [Hash] :metadata Additional customer information
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the payload is invalid or the API request fails.
+      def create(payload)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            email: {type: :email, required: true},
+            first_name: {type: :string, required: false},
+            last_name: {type: :string, required: false},
+            phone: {type: :string, required: false}
+          }
+        )
+
+        response = @connection.post("customer", payload)
+        handle_response(response)
+      end
+
+      # Lists all customers.
+      #
+      # @param per_page [Integer] Number of records per page (default: 50)
+      # @param page [Integer] Page number to retrieve (default: 1)
+      # @param from [String] Start date for filtering
+      # @param to [String] End date for filtering
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the API request fails.
+      def list(per_page: 50, page: 1, **params)
+        validate_positive_integer!(value: per_page, name: "per_page", allow_nil: true)
+        validate_positive_integer!(value: page, name: "page", allow_nil: true)
+
+        if params[:from]
+          validate_date_format!(date_str: params[:from], name: "from")
+        end
+
+        if params[:to]
+          validate_date_format!(date_str: params[:to], name: "to")
+        end
+
+        query_params = {perPage: per_page, page: page}.merge(params)
+        response = @connection.get("customer", query_params)
+        handle_response(response)
+      end
+
+      # Fetches details of a single customer by email or code.
+      #
+      # @param email_or_code [String] Email or customer code
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the parameter is invalid or the API request fails.
+      def fetch(email_or_code)
+        validate_presence!(value: email_or_code, name: "email_or_code")
+        response = @connection.get("customer/#{email_or_code}")
+        handle_response(response)
+      end
+
+      # Updates a customer's details.
+      #
+      # @param code [String] Customer's code
+      # @param payload [Hash] The payload containing customer details to update
+      # @option payload [String] :first_name Customer's first name
+      # @option payload [String] :last_name Customer's last name
+      # @option payload [String] :phone Customer's phone number
+      # @option payload [Hash] :metadata Additional customer information
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the parameters are invalid or the API request fails.
+      def update(code, payload)
+        validate_presence!(value: code, name: "code")
+        validate_hash!(input: payload, name: "payload")
+
+        response = @connection.put("customer/#{code}", payload)
+        handle_response(response)
+      end
+
+      # Validates a customer's identity.
+      #
+      # @param code [String] Customer's code
+      # @param payload [Hash] The payload containing validation details
+      # @option payload [String] :country (required) 2 letter country code
+      # @option payload [String] :type (required) Type of identification
+      # @option payload [String] :account_number Bank account number (required for bank_account type)
+      # @option payload [String] :bvn Bank Verification Number
+      # @option payload [String] :bank_code Bank code
+      # @option payload [String] :first_name Customer's first name
+      # @option payload [String] :last_name Customer's last name
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the parameters are invalid or the API request fails.
+      def validate(code, payload)
+        validate_presence!(value: code, name: "code")
+        validate_fields!(
+          payload: payload,
+          validations: {
+            country: {type: :string, required: true},
+            type: {type: :string, required: true},
+            account_number: {type: :string, required: true},
+            bank_code: {type: :string, required: true}
+          }
+        )
+
+        response = @connection.post("customer/#{code}/identification", payload)
+        handle_response(response)
+      end
+
+      # Sets the risk action for a customer.
+      #
+      # @param payload [Hash] The payload containing risk action details
+      # @option payload [String] :customer (required) Customer's code or email address
+      # @option payload [String] :risk_action (required) Risk action to set ('default', 'allow', or 'deny')
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::MissingParamError] If required parameters are missing
+      # @raise [PaystackSdk::InvalidValueError] If risk_action is not one of the allowed values
+      # @raise [PaystackSdk::APIError] If the API request fails.
+      #
+      # @example
+      # ```ruby
+      #   payload = { customer: "CUS_xxxxx", risk_action: "allow" }
+      #   response = customers.set_risk_action(payload)
+      #   if response.success?
+      #     puts "Risk action updated successfully"
+      #   end
+      # ```
+      def set_risk_action(payload)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            customer: {type: :string, required: true},
+            risk_action: {type: :inclusion, required: true, allowed_values: %w[default allow deny]}
+          }
+        )
+
+        response = @connection.post("customer/set_risk_action", payload)
+        handle_response(response)
+      end
+
+      # Deactivates a customer's authorization.
+      #
+      # @param payload [Hash] The payload containing authorization details
+      # @option payload [String] :authorization_code (required) Authorization code to deactivate
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the parameters are invalid or the API request fails.
+      def deactivate_authorization(payload)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            authorization_code: {type: :string, required: true}
+          }
+        )
+
+        response = @connection.post("customer/deactivate_authorization", payload)
+        handle_response(response)
+      end
+    end
+  end
+end

data/lib/paystack_sdk/response.rb

@@ -3,12 +3,17 @@ module PaystackSdk
   # It offers convenient access to response data through dot notation and
   # supports both direct attribute access and hash/array-like operations.
   #
+  # The Response class handles API responses that use string keys (as returned
+  # by the Paystack API) and provides seamless access through both string and
+  # symbol notation.
+  #
   # Features:
   # - Dynamic attribute access via dot notation (response.data.attribute)
-  # - Hash-like access (response[:key])
+  # - Hash-like access (response[:key] or response["key"])
   # - Array-like access for list responses (response[0])
   # - Iteration support (response.each)
   # - Automatic handling of nested data structures
+  # - Consistent handling of string-keyed API responses
   #
   # @example Basic usage
   # ```ruby
@@ -49,28 +54,48 @@ module PaystackSdk
     # @return [Hash, Array, Object] The underlying data
     attr_reader :raw_data
 
+    # @return [Integer] The status code of the API response
+    attr_reader :status_code
+
     # 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
     def initialize(response)
       if response.is_a?(Faraday::Response)
-        # Handle direct Faraday response
-        @success = response.success?
+        @status_code = response.status
         @body = response.body
         @api_message = extract_api_message(@body)
         @raw_data = extract_data_from_body(@body)
 
-        unless @success
-          @error_message = @api_message || "Paystack API Error"
+        case @status_code
+        when 200..299
+          @success = true
+        when 400
+          handle_400_response
+        when 401
+          raise AuthenticationError.new
+        when 404
+          handle_404_response
+        when 429
+          retry_after = response.headers["Retry-After"]
+          raise RateLimitError.new(retry_after || 30)
+        when 500..599
+          raise ServerError.new(@status_code, @api_message)
+        else
+          @success = false
+          raise APIError.new(@api_message || "Paystack API Error")
         end
       elsif response.is_a?(Response)
-        # If we're wrapping a Response object, just copy its data
-        @success = response.success
+        @success = response.success?
         @error_message = response.error_message
         @api_message = response.api_message
         @raw_data = response.raw_data
       else
-        # For direct data (Hash, Array, etc.)
         @success = true
         @raw_data = response
       end
@@ -197,24 +222,44 @@ module PaystackSdk
 
     private
 
-    # Extract API message from response body
+    # Extract the identifier from an error response
+    # This looks for common patterns in error messages to find resource identifiers
     #
     # @param body [Hash] The response body
-    # @return [String, nil] The API message
+    # @return [String] The extracted identifier or "unknown"
+    def extract_identifier(body)
+      return "unknown" unless body.is_a?(Hash)
+
+      # First try to get identifier from the message
+      message = body["message"].to_s.downcase
+      if message =~ /with (id|code|reference|email): ([^\s]+)/i
+        return $2
+      end
+
+      # If not found in message, try to extract from error code
+      if body["code"]&.match?(/^(transaction|customer)_/)
+        parts = body["code"].to_s.split("_")
+        return parts.last if parts.last != "not_found"
+      end
+
+      "unknown"
+    end
+
+    # Extract the API message from the response body
+    #
+    # @param body [Hash, nil] The response body
+    # @return [String, nil] The API message if present
     def extract_api_message(body)
-      body["message"] || body[:message] if body.is_a?(Hash)
+      body["message"] if body.is_a?(Hash) && body["message"]
     end
 
-    # Extract data from response body
+    # Extract the data from the response body
     #
-    # @param body [Hash, Array] The response body
-    # @return [Hash, Array, Object] The data portion of the response
+    # @param body [Hash, nil] The response body
+    # @return [Hash, Array, nil] The data from the response
     def extract_data_from_body(body)
-      if body.is_a?(Hash)
-        body["data"] || body[:data] || body
-      else
-        body
-      end
+      return body unless body.is_a?(Hash)
+      body["data"] || body
     end
 
     # Wrap value in Response if needed
@@ -234,5 +279,29 @@ module PaystackSdk
         value
       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 handle_404_response
+      resource_type = determine_resource_type
+      raise ResourceNotFoundError.new(resource_type, @api_message)
+    end
+
+    def determine_resource_type
+      resource = @body["code"].split("_").first
+      resource.capitalize
+    end
   end
 end

data/lib/paystack_sdk/utils/connection_utils.rb

@@ -23,7 +23,7 @@ module PaystackSdk
         else
           # Try to get API key from environment variable
           env_secret_key = ENV["PAYSTACK_SECRET_KEY"]
-          raise PaystackSdk::Error, "No connection or API key provided" unless env_secret_key
+          raise AuthenticationError, "No connection or API key provided" unless env_secret_key
 
           create_connection(secret_key: env_secret_key)
         end

data/lib/paystack_sdk/validations.rb

@@ -5,15 +5,41 @@ module PaystackSdk
   # It includes methods for validating common parameters like references, amounts, dates, etc.
   #
   # This module is intended to be included in resource classes to provide consistent
-  # parameter validation before making API calls.
+  # parameter validation before making API calls. All validation methods raise specific
+  # error types to enable proper error handling in client applications.
+  #
+  # @example Usage in a resource class
+  # ```ruby
+  #   class MyResource < PaystackSdk::Resources::Base
+  #     include PaystackSdk::Validations
+  #
+  #     def create(payload)
+  #       validate_fields!(
+  #         payload: payload,
+  #         validations: {
+  #           email: { type: :email, required: true },
+  #           amount: { type: :positive_integer, required: true },
+  #           currency: { type: :currency, required: true }
+  #         }
+  #       )
+  #       # Make API call...
+  #     end
+  #   end
+  # ```
+  #
+  # @see PaystackSdk::MissingParamError
+  # @see PaystackSdk::InvalidFormatError
+  # @see PaystackSdk::InvalidValueError
   module Validations
     # Validates that input is a hash.
     #
     # @param input [Object] The input to validate
     # @param name [String] Name of the parameter for error messages
-    # @raise [PaystackSdk::Error] If input is not a hash
+    # @raise [PaystackSdk::InvalidFormatError] If input is not a hash
     def validate_hash!(input:, name: "Payload")
-      raise PaystackSdk::Error, "#{name} must be a hash" unless input.is_a?(Hash)
+      unless input.is_a?(Hash)
+        raise PaystackSdk::InvalidFormatError.new(name, "Hash")
+      end
     end
 
     # Validates that required parameters are present in a payload.
@@ -21,15 +47,15 @@ module PaystackSdk
     # @param payload [Hash] The payload to validate
     # @param required_params [Array<Symbol>] List of required parameter keys
     # @param operation_name [String] Name of the operation for error messages
-    # @raise [PaystackSdk::Error] If any required parameters are missing
+    # @raise [PaystackSdk::MissingParamError] If any required parameters are missing
     def validate_required_params!(payload:, required_params:, operation_name: "Operation")
       missing_params = required_params.select do |param|
         !payload.key?(param) && !payload.key?(param.to_s)
       end
 
       unless missing_params.empty?
-        missing_list = missing_params.map(&:to_s).join(", ")
-        raise PaystackSdk::Error, "#{operation_name} requires these missing parameter(s): #{missing_list}"
+        param = missing_params.first
+        raise PaystackSdk::MissingParamError.new(param)
       end
     end
 
@@ -37,10 +63,10 @@ module PaystackSdk
     #
     # @param value [Object] The value to validate
     # @param name [String] Name of the parameter for error messages
-    # @raise [PaystackSdk::Error] If value is nil or empty
+    # @raise [PaystackSdk::MissingParamError] If value is nil or empty
     def validate_presence!(value:, name: "Parameter")
       if value.nil? || (value.respond_to?(:empty?) && value.empty?)
-        raise PaystackSdk::Error, "#{name} cannot be empty"
+        raise PaystackSdk::MissingParamError.new(name)
       end
     end
 
@@ -49,12 +75,13 @@ module PaystackSdk
     # @param value [Object] The value to validate
     # @param name [String] Name of the parameter for error messages
     # @param allow_nil [Boolean] Whether nil values are allowed
-    # @raise [PaystackSdk::Error] If value is not a positive integer (and not nil if allow_nil is true)
+    # @raise [PaystackSdk::InvalidValueError] If value is not a positive integer
+    # @raise [PaystackSdk::MissingParamError] If value is nil and not allowed
     def validate_positive_integer!(value:, name: "Parameter", allow_nil: true)
       if value.nil?
-        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        raise PaystackSdk::MissingParamError.new(name) unless allow_nil
       elsif !value.is_a?(Integer) || value < 1
-        raise PaystackSdk::Error, "#{name} must be a positive integer"
+        raise PaystackSdk::InvalidValueError.new(name, "must be a positive integer")
       end
     end
 
@@ -62,10 +89,10 @@ module PaystackSdk
     #
     # @param reference [String] The reference to validate
     # @param name [String] Name of the parameter for error messages
-    # @raise [PaystackSdk::Error] If reference format is invalid
+    # @raise [PaystackSdk::InvalidFormatError] If reference format is invalid
     def validate_reference_format!(reference:, name: "Reference")
       unless reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)
-        raise PaystackSdk::Error, "#{name} can only contain alphanumeric characters and the following: -, ., ="
+        raise PaystackSdk::InvalidFormatError.new(name, "alphanumeric characters and the following: -, ., =")
       end
     end
 
@@ -74,17 +101,18 @@ module PaystackSdk
     # @param date_str [String] The date string to validate
     # @param name [String] Name of the parameter for error messages
     # @param allow_nil [Boolean] Whether nil values are allowed
-    # @raise [PaystackSdk::Error] If date format is invalid
+    # @raise [PaystackSdk::InvalidFormatError] If date format is invalid
+    # @raise [PaystackSdk::MissingParamError] If date is nil and not allowed
     def validate_date_format!(date_str:, name: "Date", allow_nil: true)
       if date_str.nil?
-        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        raise PaystackSdk::MissingParamError.new(name) unless allow_nil
         return
       end
 
       begin
         Date.parse(date_str.to_s)
       rescue Date::Error
-        raise PaystackSdk::Error, "Invalid #{name.downcase} format. Use format: YYYY-MM-DD or ISO8601"
+        raise PaystackSdk::InvalidFormatError.new(name, "YYYY-MM-DD or ISO8601")
       end
     end
 
@@ -94,20 +122,26 @@ module PaystackSdk
     # @param allowed_values [Array] List of allowed values
     # @param name [String] Name of the parameter for error messages
     # @param allow_nil [Boolean] Whether nil values are allowed
-    # @param case_sensitive [Boolean] Whether the comparison is case-sensitive
-    # @raise [PaystackSdk::Error] If value is not in the allowed set
-    def validate_inclusion!(value:, allowed_values:, name: "Parameter", allow_nil: true, case_sensitive: false)
+    # @raise [PaystackSdk::InvalidValueError] If value is not in allowed_values
+    # @raise [PaystackSdk::MissingParamError] If value is nil and not allowed
+    #
+    # @example
+    # ```ruby
+    #   validate_allowed_values!(
+    #     value: "allow",
+    #     allowed_values: %w[default allow deny],
+    #     name: "risk_action"
+    #   )
+    # ```
+    def validate_allowed_values!(value:, allowed_values:, name: "Parameter", allow_nil: true)
       if value.nil?
-        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        raise PaystackSdk::MissingParamError.new(name) unless allow_nil
         return
       end
 
-      check_value = case_sensitive ? value.to_s : value.to_s.downcase
-      check_allowed = case_sensitive ? allowed_values : allowed_values.map(&:downcase)
-
-      unless check_allowed.include?(check_value)
-        allowed_list = allowed_values.join("', '")
-        raise PaystackSdk::Error, "#{name} must be one of: '#{allowed_list}'"
+      unless allowed_values.include?(value)
+        allowed_list = allowed_values.join(", ")
+        raise PaystackSdk::InvalidValueError.new(name, "must be one of: #{allowed_list}")
       end
     end
 
@@ -119,12 +153,12 @@ module PaystackSdk
     # @raise [PaystackSdk::Error] If email format is invalid
     def validate_email!(email:, name: "Email", allow_nil: false)
       if email.nil?
-        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        raise PaystackSdk::MissingParamError.new(name) unless allow_nil
         return
       end
 
       unless email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
-        raise PaystackSdk::Error, "Invalid #{name.downcase} format"
+        raise PaystackSdk::InvalidFormatError.new(name, "valid email address")
       end
     end
 
@@ -136,12 +170,12 @@ module PaystackSdk
     # @raise [PaystackSdk::Error] If currency format is invalid
     def validate_currency!(currency:, name: "Currency", allow_nil: true)
       if currency.nil?
-        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        raise PaystackSdk::MissingParamError.new(name) unless allow_nil
         return
       end
 
       unless currency.to_s.match?(/\A[A-Z]{3}\z/)
-        raise PaystackSdk::Error, "#{name} must be a 3-letter ISO code (e.g., NGN, USD, GHS)"
+        raise PaystackSdk::InvalidFormatError.new(name, "3-letter ISO code (e.g., NGN, USD, GHS)")
       end
     end
 
@@ -152,6 +186,7 @@ module PaystackSdk
     # @raise [PaystackSdk::Error] If any validation fails
     #
     # @example
+    # ```ruby
     #   validate_fields!(
     #     payload: params,
     #     validations: {
@@ -161,7 +196,10 @@ module PaystackSdk
     #       reference: { type: :reference, required: false }
     #     }
     #   )
+    # ```
     def validate_fields!(payload:, validations:)
+      validate_hash!(input: payload, name: "Payload")
+
       # First check required fields
       required_fields = validations.select { |_, opts| opts[:required] }.keys
       validate_required_params!(payload: payload, required_params: required_fields) unless required_fields.empty?
@@ -184,14 +222,15 @@ module PaystackSdk
           validate_currency!(currency: value, name: field.to_s, allow_nil: !options[:required])
         when :inclusion
           if value
-            validate_inclusion!(
+            validate_allowed_values!(
               value: value,
               allowed_values: options[:allowed_values],
               name: field.to_s,
-              allow_nil: !options[:required],
-              case_sensitive: options[:case_sensitive]
+              allow_nil: !options[:required]
             )
           end
+        when :string
+          validate_presence!(value: value, name: field.to_s) if !options[:allow_nil] && options[:required]
         end
       end
     end

data/lib/paystack_sdk/version.rb

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

data/lib/paystack_sdk.rb

@@ -5,5 +5,87 @@ require_relative "paystack_sdk/version"
 require_relative "paystack_sdk/client"
 
 module PaystackSdk
+  # Base error class for all Paystack SDK errors.
+  # All SDK-specific exceptions inherit from this class.
   class Error < StandardError; end
+
+  # Base class for all validation errors.
+  # Raised when input parameters fail validation before API calls.
+  class ValidationError < Error; end
+
+  # Raised when a required parameter is missing.
+  # Contains the parameter name for detailed error handling.
+  class MissingParamError < ValidationError
+    attr_reader :param_name
+
+    def initialize(param_name)
+      @param_name = param_name
+      super("Missing required parameter: #{param_name}")
+    end
+  end
+
+  # Raised when a parameter has an invalid format.
+  # Contains both the parameter name and expected format for detailed error handling.
+  class InvalidFormatError < ValidationError
+    attr_reader :param_name, :expected_format
+
+    def initialize(param_name, expected_format)
+      @param_name = param_name
+      @expected_format = expected_format
+      super("Invalid format for #{param_name}. Expected format: #{expected_format}")
+    end
+  end
+
+  # Raised when a parameter has an invalid value.
+  # Contains both the parameter name and the reason for the invalid value.
+  class InvalidValueError < ValidationError
+    attr_reader :param_name, :reason
+
+    def initialize(param_name, reason)
+      @param_name = param_name
+      @reason = reason
+      super("Invalid value for #{param_name}: #{reason}")
+    end
+  end
+
+  # Base class for API errors.
+  # Raised when the Paystack API returns an error response.
+  class APIError < Error; end
+
+  # Raised when authentication fails
+  class AuthenticationError < APIError
+    def initialize(message = "Invalid API key or authentication failed")
+      super
+    end
+  end
+
+  # Raised when a resource is not found
+  class ResourceNotFoundError < APIError
+    attr_reader :resource_type
+
+    def initialize(resource_type, message)
+      @resource_type = resource_type
+      super(message)
+    end
+  end
+
+  # Raised when rate limiting is encountered
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(retry_after)
+      @retry_after = retry_after
+      super("Rate limit exceeded. Retry after #{retry_after} seconds")
+    end
+  end
+
+  # Raised when the server returns a 5xx error
+  class ServerError < APIError
+    attr_reader :status_code
+
+    def initialize(status_code, message = "An error occurred on the Paystack server")
+      @status_code = status_code
+      super("#{message} (Status: #{status_code})")
+    end
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: paystack_sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Maxwell Nana Forson (theLazyProgrammer)
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -117,6 +116,7 @@ files:
 - lib/paystack_sdk.rb
 - lib/paystack_sdk/client.rb
 - lib/paystack_sdk/resources/base.rb
+- lib/paystack_sdk/resources/customers.rb
 - lib/paystack_sdk/resources/transactions.rb
 - lib/paystack_sdk/response.rb
 - lib/paystack_sdk/utils/connection_utils.rb
@@ -131,7 +131,6 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/nanafox/paystack_sdk
   changelog_uri: https://github.com/nanafox/paystack_sdk/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -146,8 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Ruby SDK for integrating with Paystack's payment gateway API.
 test_files: []