paystack_sdk 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6c4ffb56d54aca1c129d5f8d9c825e31f0c4f0df719a95c324eb8b220156f2f
-  data.tar.gz: 8a5a351599e8795c3c61deb5d8d2737c5fb5e445e20bf7c72b357bf0fb84f0ca
+  metadata.gz: cfe0137a6cc918043bc34e2be6dcb579713ef3dfec0641763234e66d51e08717
+  data.tar.gz: a331be86e1c23da3621d4b6a1d6d6c5ecfa31de7685c3776872b3ff6f3adc99d
 SHA512:
-  metadata.gz: c9c76e4b0ef258ac320e4088d15ba07d7703d3436ad57246b22ab079873b9a0f590553dd0b712d8e2c2a4a3220c41090000d1fa115b83650a5e00780d519f033
-  data.tar.gz: cf9454f62965fbc0555303a83f658ebf6cf7f249605a263a429dfa6d5da9810db5bb4b5ed76ea844f0228bb391ce21b0143b7a7846f343515705d07b5479e248
+  metadata.gz: de4c777e2d89ce4cf1e30a13a352d4dab8bee5696716af0eb771964ce3aad3a10b0a6381c67b64c42dea342954c5e6d69d05b75fa43e72c288f55eeb45192a7d
+  data.tar.gz: cc889820541066ea486dfe9b4aa86d1009c692efd7c1fa52929a0791ae1f954ecabd0c66bb75b733bae0af44398e6687004867a78dc64bf7f33b33ec81eaebbc

data/README.md

@@ -36,19 +36,37 @@ paystack = PaystackSdk::Client.new(api_key: "sk_test_xxx")
 params = {email: "customer@email.com", amount: "2300", currency: "USD"}
 response = paystack.transactions.initialize_transaction(params)
 
+if response.success?
+  puts response.authorization_url
+else
+  puts resposne.error_message
+end
+
 # Example: Verify a payment
 response = paystack.transactions.verify(reference: "transaction_reference")
-if paystack.transactions.success?
+if response.success?
   puts "Payment verified successfully!"
 else
   puts "Payment verification failed: #{response.error_message}"
 end
+```
+
+### The Orginal Response
 
-# Note: The `response` object is a hash containing the API response. Use the `#success?`
-# method on the relevant resource instance (e.g., `transactions`, `plans`, `subscriptions`)
-# to determine if the request was successful.
+There will be times you may need access to the original API response. For such cases, you
+can use the `#original_response` method on the response object.
+
+The return value is a hash with all the values from the HTTP request. This could be useful
+when you need to debug or gain access to the response its raw state.
+
+For example
+```ruby
+response = transaction.list
+
+puts response.original_response # => This will return the exact response received from Paystack
 ```
 
+
 Refer to the [documentation](https://github.com/nanafox/paystack_sdk) for more detailed usage examples and supported endpoints.
 
 ## Development

data/lib/paystack_sdk/resources/base.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../response"
+
 module PaystackSdk
   module Resources
     # The `Base` class serves as a parent class for all resource classes in the SDK.
@@ -10,29 +14,15 @@ module PaystackSdk
         @connection = connection
       end
 
-      # Checks if the last API response was successful.
-      #
-      # @return [Boolean] `true` if the last API response was successful, otherwise `false`.
-      def success?
-        @api_response&.success? || false
-      end
-
       private
 
       # Handles the API response, raising an error if the response is unsuccessful.
       #
       # @param response [Faraday::Response] The response object returned by the Faraday connection.
-      # @return [Hash] The parsed response body if the request was successful.
+      # @return [PaystackSdk::Response] The parsed response body wrapped in a `PaystackSdk::Response` object if the request was successful.
       # @raise [PaystackSdk::Error] If the response indicates an error.
       def handle_response(response)
-        @api_response ||= response
-
-        if response.success?
-          response.body
-        else
-          error_message = response.body.is_a?(Hash) ? response.body["message"] : "Paystack API Error"
-          raise PaystackSdk::Error, error_message
-        end
+        PaystackSdk::Response.new(response)
       end
     end
   end

data/lib/paystack_sdk/resources/transactions.rb

@@ -4,8 +4,38 @@ require_relative "base"
 
 module PaystackSdk
   module Resources
-    # The `Transactions` class provides methods for interacting with the Paystack Transactions API.
+    # The `Transactions` class provides methods for interacting with the Paystack
+    #  Transactions API.
     # It allows you to initialize transactions, verify payments, list transactions, and fetch transaction details.
+    # The Transactions class provides methods to interact with the Paystack API for managing transactions.
+    # It includes functionalities for initializing, verifying, listing, fetching, and retrieving transaction totals.
+    #
+    # Example usage:
+    # ```ruby
+    #   transactions = PaystackSdk::Resources::Transactions.new(connection)
+    #
+    #   # Initialize a transaction
+    #   payload = { email: "customer@email.com", amount: 10000, currency: "GHS" }
+    #   response = transactions.initialize_transaction(payload)
+    #   if response.success?
+    #     puts "Transaction initialized successfully."
+    #     puts "Authorization URL: #{response.data.authorization_url}"
+    #   else
+    #     puts "Error initializing transaction: #{response.error_message}"
+    #   end
+    #
+    #   # Verify a transaction
+    #   response = transactions.verify(reference: "transaction_reference")
+    #
+    #   # List transactions
+    #   response = transactions.list(per_page: 50, page: 1)
+    #
+    #   # Fetch a single transaction
+    #   response = transactions.fetch(transaction_id: 12345)
+    #
+    #   # Get transaction totals
+    #   response = transactions.totals
+    # ```
     class Transactions < PaystackSdk::Resources::Base
       # Initializes a new transaction.
       #
@@ -16,8 +46,8 @@ module PaystackSdk
       # @example
       #   payload = { email: "customer@email.com", amount: 10000, currency: "GHS" }
       #   response = transactions.initialize_transaction(payload)
-      def initialize_transaction(payload)
-        raise PaystackSdk::Error, "Invalid payload" unless payload.is_a?(Hash)
+      def initiate(payload)
+        raise PaystackSdk::Error, "Payload must be a hash" unless payload.is_a?(Hash)
         response = @connection.post("/transaction/initialize", payload)
         handle_response(response)
       end
@@ -37,26 +67,29 @@ module PaystackSdk
 
       # Lists all transactions.
       #
-      # @return [Hash] The response from the Paystack API containing a list of transactions.
+      # @param per_page [Integer] Number of records per page (default: 50)
+      # @param page [Integer] Page number to retrieve (default: 1)
+      # @return [PaystackSdk::Response] The response from the Paystack API containing a
+      # list of transactions.
       # @raise [PaystackSdk::Error] If the API request fails.
       #
       # @example
-      #   response = transactions.list
-      def list
-        response = @connection.get("/transaction")
+      #   response = transactions.list(per_page: 20, page: 2)
+      def list(per_page: 50, page: 1)
+        response = @connection.get("/transaction", {perPage: per_page, page: page})
         handle_response(response)
       end
 
       # Fetches details of a single transaction by its ID.
       #
-      # @param id [Integer] The ID of the transaction to fetch.
+      # @param transaction_id [Integer] The ID of the transaction to fetch.
       # @return [Hash] The response from the Paystack API containing transaction details.
       # @raise [PaystackSdk::Error] If the API request fails.
       #
       # @example
       #   response = transactions.fetch("transaction_id")
-      def fetch(id)
-        response = @connection.get("/transaction/#{id}")
+      def fetch(transaction_id)
+        response = @connection.get("/transaction/#{transaction_id}")
         handle_response(response)
       end
 

data/lib/paystack_sdk/response.rb

@@ -0,0 +1,238 @@
+module PaystackSdk
+  # The Response class provides a wrapper around Paystack API responses.
+  # It offers convenient access to response data through dot notation and
+  # supports both direct attribute access and hash/array-like operations.
+  #
+  # Features:
+  # - Dynamic attribute access via dot notation (response.data.attribute)
+  # - Hash-like access (response[:key])
+  # - Array-like access for list responses (response[0])
+  # - Iteration support (response.each)
+  # - Automatic handling of nested data structures
+  #
+  # @example Basic usage
+  # ```ruby
+  #   response = PaystackSdk::Response.new(api_response)
+  #
+  #   # Check if request was successful
+  #   if response.success?
+  #     # Access data using dot notation
+  #     puts response.data.authorization_url
+  #     puts response.data.reference
+  #
+  #     # Or directly from response
+  #     puts response.authorization_url
+  #   else
+  #     puts "Error: #{response.error_message}"
+  #   end
+  #
+  # @example Working with list responses
+  #   response = transactions.list
+  #
+  #   # Iterate through items
+  #   response.data.each do |transaction|
+  #     puts transaction.amount
+  #     puts transaction.reference
+  #   end
+  #
+  #   # Access by index
+  #   first_transaction = response.data[0] # => same as `response.first`
+  #   puts first_transaction.customer.email
+  #   ```
+  class Response
+    # @return [String, nil] Error message if the request failed
+    attr_reader :error_message
+
+    # @return [String, nil] API message from the response
+    attr_reader :api_message
+
+    # @return [Hash, Array, Object] The underlying data
+    attr_reader :raw_data
+
+    # Initializes a new Response object
+    #
+    # @param response [Faraday::Response, Hash, Array] The raw API response or data
+    def initialize(response)
+      if response.is_a?(Faraday::Response)
+        # Handle direct Faraday response
+        @success = response.success?
+        @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"
+        end
+      elsif response.is_a?(Response)
+        # If we're wrapping a Response object, just copy its data
+        @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
+    end
+
+    # Returns a Response object for the data
+    # This enables chained access like response.data.key
+    #
+    # @return [Response] self, to enable chaining
+    def data
+      self
+    end
+
+    # Check if the response was successful
+    #
+    # @return [Boolean] true if the API request was successful
+    def success?
+      @success
+    end
+
+    # Returns the original response body
+    # This is useful for debugging or accessing raw data
+    #
+    # @return [Hash, Array] The original response body
+    def original_response
+      @body
+    end
+
+    # Access hash values via methods (dot notation)
+    # Allows accessing data attributes directly: response.attribute_name
+    #
+    # @param method_name [Symbol] The attribute name to access
+    # @param args [Array] Method arguments (unused)
+    # @param block [Proc] Method block (unused)
+    # @return [Object, Response] The attribute value, wrapped in Response if it's a complex type
+    def method_missing(method_name, *args, &block)
+      if @raw_data.is_a?(Hash) && (@raw_data.key?(method_name) || @raw_data.key?(method_name.to_s))
+        value = @raw_data[method_name] || @raw_data[method_name.to_s]
+        wrap_value(value)
+      elsif @raw_data.is_a?(Array) && @raw_data.respond_to?(method_name)
+        result = @raw_data.send(method_name, *args, &block)
+        wrap_value(result)
+      else
+        super
+      end
+    end
+
+    # Check if the object responds to a method
+    #
+    # @param method_name [Symbol] The method name
+    # @param include_private [Boolean] Whether to include private methods
+    # @return [Boolean] Whether the method is supported
+    def respond_to_missing?(method_name, include_private = false)
+      (@raw_data.is_a?(Hash) && (@raw_data.key?(method_name) || @raw_data.key?(method_name.to_s))) ||
+        (@raw_data.is_a?(Array) && @raw_data.respond_to?(method_name)) ||
+        super
+    end
+
+    # Access data via hash/array notation
+    #
+    # @param key [Object] The key or index to access
+    # @return [Object, Response] The value for the given key or index
+    def [](key)
+      return nil unless @raw_data
+
+      if @raw_data.is_a?(Hash)
+        value = @raw_data[key.is_a?(String) ? key.to_sym : key]
+        wrap_value(value)
+      elsif @raw_data.is_a?(Array) && key.is_a?(Integer)
+        wrap_value(@raw_data[key])
+      end
+    end
+
+    # Check if key exists in hash
+    #
+    # @param key [Symbol, String] The key to check
+    # @return [Boolean] Whether the key exists
+    def key?(key)
+      @raw_data.is_a?(Hash) && @raw_data.key?(key.is_a?(String) ? key.to_sym : key)
+    end
+
+    # Iterate through hash entries or array items
+    #
+    # @yield [key, value] For hashes, passes each key-value pair
+    # @yield [value] For arrays, passes each item
+    # @return [Response, Enumerator] Self for chaining or Enumerator if no block given
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      if @raw_data.is_a?(Hash)
+        @raw_data.each { |k, v| yield k, wrap_value(v) }
+      elsif @raw_data.is_a?(Array)
+        @raw_data.each { |item| yield wrap_value(item) }
+      end
+      self
+    end
+
+    # Standard array methods, delegated to the raw data
+    # @!method size
+    #   @return [Integer] The number of items
+    # @!method length
+    #   @return [Integer] The number of items
+    # @!method count
+    #   @return [Integer] The number of items
+    # @!method empty?
+    #   @return [Boolean] Whether the collection is empty
+    [:size, :length, :count, :empty?].each do |method_name|
+      define_method(method_name) do
+        @raw_data.send(method_name) if @raw_data.respond_to?(method_name)
+      end
+    end
+
+    # Special array methods that return wrapped values
+    # @!method first
+    #   @return [Object, Response] The first item, wrapped if necessary
+    # @!method last
+    #   @return [Object, Response] The last item, wrapped if necessary
+    [:first, :last].each do |method_name|
+      define_method(method_name) do
+        return nil unless @raw_data.is_a?(Array)
+        wrap_value(@raw_data.send(method_name))
+      end
+    end
+
+    private
+
+    # Extract API message from response body
+    #
+    # @param body [Hash] The response body
+    # @return [String, nil] The API message
+    def extract_api_message(body)
+      body["message"] || body[:message] if body.is_a?(Hash)
+    end
+
+    # Extract data from response body
+    #
+    # @param body [Hash, Array] The response body
+    # @return [Hash, Array, Object] The data portion of the response
+    def extract_data_from_body(body)
+      if body.is_a?(Hash)
+        body["data"] || body[:data] || body
+      else
+        body
+      end
+    end
+
+    # Wrap value in Response if needed
+    #
+    # @param value [Object] The value to wrap
+    # @return [Object, Response] The wrapped value
+    def wrap_value(value)
+      case value
+      when Response
+        # Already wrapped
+        value
+      when Hash, Array
+        # Create a new Response with the value
+        Response.new(value)
+      else
+        # Return primitives as-is
+        value
+      end
+    end
+  end
+end

data/lib/paystack_sdk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paystack_sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Maxwell Nana Forson (theLazyProgrammer)
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-10 00:00:00.000000000 Z
+date: 2025-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 13.2.1
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.9.0
 description: |
   The `paystack_sdk` gem provides a simple and intuitive interface for
   interacting with Paystack's payment gateway API. It allows developers to
@@ -104,6 +118,7 @@ files:
 - lib/paystack_sdk/client.rb
 - lib/paystack_sdk/resources/base.rb
 - lib/paystack_sdk/resources/transactions.rb
+- lib/paystack_sdk/response.rb
 - lib/paystack_sdk/version.rb
 - mise.toml
 - sig/paystack_sdk.rbs