paystack_sdk 0.1.1 → 0.2.0

data/lib/paystack_sdk/resources/transfer_recipients.rb

@@ -1,46 +1,154 @@
-require_relative "../validations"
+# frozen_string_literal: true
+
+# Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
+# Do not edit by hand: regenerate it with `bin/paystack-scaffold Transfer Recipient`. Hand-written extras go in lib/paystack_sdk/resources/extensions/transfer_recipients.rb.
+# scaffold-digest: 74785aa38f6edfebdeff52d47bb3b355c2ad95b2cacdd6c0d7062725415bbfaa
+
+require_relative "base"
 
 module PaystackSdk
   module Resources
-    class TransferRecipients < Base
-      # Create a transfer recipient
+    # Transfer Recipient operations.
+    class TransferRecipients < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {next_cursor: "next", per_page: "perPage"}.freeze
+
+      # List Transfer Recipients.
+      #
+      # List transfer recipients available on your integration
+      #
+      # @param use_cursor [Boolean] A flag to indicate if cursor based pagination should be used
+      # @param next_cursor [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
+      # @param per_page [Integer] The number of records to fetch per request
+      # @param page [Integer] The offset to retrieve data from
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-recipient/#list
+      def list(use_cursor: nil, next_cursor: nil, previous: nil, per_page: nil, page: nil)
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+
+        wire_query = to_wire({use_cursor:, next_cursor:, previous:, per_page:, page:}, WIRE_NAMES)
+
+        handle_response(@connection.get("/transferrecipient", wire_query))
+      end
+
+      # Create Transfer Recipient.
+      #
+      # Creates a new recipient. A duplicate account number will lead to the retrieval of the existing record.
+      #
+      # @param type [String] Recipient Type One of: nuban, ghipss, mobile_money, basa, authorization.
+      # @param name [String] The recipient's name according to their account registration.
+      # @param account_number [String] Recipient's bank account number
+      # @param bank_code [String] Recipient's bank code, from the List Banks endpoint.
+      # @param description [String] A description for this recipient
+      # @param currency [String] Currency for the account receiving the transfer
+      # @param authorization_code [String] An authorization code from a previous transaction
+      # @param metadata [Hash] JSON object of custom data
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#create
-      def create(params)
-        validate_hash!(input: params, name: "TransferRecipient params")
-        validate_required_params!(
-          payload: params,
-          required_params: %i[type name account_number bank_code],
-          operation_name: "Create Transfer Recipient"
+      def create(
+        type:,
+        name:,
+        account_number:,
+        bank_code:,
+        description: nil,
+        currency: nil,
+        authorization_code: nil,
+        metadata: nil
+      )
+        validate_presence!(value: type, name: "type")
+        validate_allowed_values!(
+          value: type,
+          allowed_values: %w[nuban ghipss mobile_money basa authorization],
+          name: "type"
+        )
+        validate_presence!(value: name, name: "name")
+        validate_presence!(value: account_number, name: "account_number")
+        validate_presence!(value: bank_code, name: "bank_code")
+
+        wire_body = to_wire(
+          {
+            type:,
+            name:,
+            account_number:,
+            bank_code:,
+            description:,
+            currency:,
+            authorization_code:,
+            metadata:
+          },
+          WIRE_NAMES
         )
-        handle_response(@connection.post("/transferrecipient", params))
+
+        handle_response(@connection.post("/transferrecipient", wire_body))
       end
 
-      # List transfer recipients
-      # @see https://paystack.com/docs/api/transfer-recipient/#list
-      def list(query = {})
-        handle_response(@connection.get("/transferrecipient", query))
+      # Bulk Create Transfer Recipient.
+      #
+      # Create multiple transfer recipients in batches. A duplicate account number will lead to the retrieval of the existing record.
+      #
+      # @param batch [Array<Hash>] A list of transfer recipient objects, each with the fields accepted by {#create}
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-recipient/#bulk
+      def bulk_create(batch:)
+        validate_presence!(value: batch, name: "batch")
+
+        wire_body = to_wire({batch:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transferrecipient/bulk", wire_body))
       end
 
-      # Fetch a transfer recipient
+      # Fetch Transfer recipient.
+      #
+      # Fetch the details of a transfer recipient
+      #
+      # @param id_or_code [String] The recipient code (RCP_...) or numeric ID
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#fetch
-      def fetch(recipient_code:)
-        validate_presence!(value: recipient_code, name: "recipient_code")
-        handle_response(@connection.get("/transferrecipient/#{recipient_code}"))
+      def fetch(id_or_code:)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+
+        handle_response(@connection.get("/transferrecipient/#{escape_path(id_or_code, name: "id_or_code")}"))
       end
 
-      # Update a transfer recipient
+      # Update Transfer Recipient.
+      #
+      # Update the details of a transfer recipient
+      #
+      # @param id_or_code [String] The recipient code (RCP_...) or numeric ID
+      # @param name [String] Recipient's name
+      # @param email [String] Recipient's email address
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#update
-      def update(recipient_code:, params:)
-        validate_presence!(value: recipient_code, name: "recipient_code")
-        validate_hash!(input: params, name: "Update TransferRecipient params")
-        handle_response(@connection.put("/transferrecipient/#{recipient_code}", params))
+      def update(id_or_code:, name: nil, email: nil)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+        validate_email!(email: email, name: "email", allow_nil: true)
+
+        wire_body = to_wire({name:, email:}, WIRE_NAMES)
+
+        handle_response(
+          @connection.put("/transferrecipient/#{escape_path(id_or_code, name: "id_or_code")}", wire_body)
+        )
       end
 
-      # Delete a transfer recipient
+      # Delete Transfer Recipient.
+      #
+      # Delete a transfer recipient (sets the transfer recipient to inactive)
+      #
+      # @param id_or_code [String] The recipient code (RCP_...) or numeric ID
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#delete
-      def delete(recipient_code:)
-        validate_presence!(value: recipient_code, name: "recipient_code")
-        handle_response(@connection.delete("/transferrecipient/#{recipient_code}"))
+      def delete(id_or_code:)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+
+        handle_response(@connection.delete("/transferrecipient/#{escape_path(id_or_code, name: "id_or_code")}"))
       end
     end
   end

data/lib/paystack_sdk/resources/transfers.rb

@@ -1,46 +1,281 @@
-require_relative "../validations"
+# frozen_string_literal: true
+
+# Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d), then
+# edited by hand against Paystack's Transfers and Transfers Control docs pages (descriptions, docs
+# links and the `fetch(id_or_code:)` keyword), so the scaffold treats it as hand-written and will not regenerate it.
+# Hand-written extras go in lib/paystack_sdk/resources/extensions/transfers.rb.
+
+require_relative "base"
 
 module PaystackSdk
   module Resources
-    class Transfers < Base
-      # Create a transfer
-      # @see https://paystack.com/docs/api/transfer/#initiate
-      def create(params)
-        validate_hash!(input: params, name: "Transfer params")
-        validate_required_params!(
-          payload: params,
-          required_params: %i[source amount recipient],
-          operation_name: "Create Transfer"
-        )
-        handle_response(@connection.post("/transfer", params))
-      end
+    # Transfer operations: send money from your balance to transfer recipients, and manage the OTP
+    # requirement that guards them.
+    class Transfers < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {next_cursor: "next", per_page: "perPage"}.freeze
 
-      # List transfers
+      # List Transfers.
+      #
+      # List the transfers made on your integration.
+      #
+      # @param use_cursor [Boolean] Set to true to use cursor-based pagination (the response meta then carries `next` and `previous`)
+      # @param next_cursor [String] The `next` cursor from a previous cursor-based response
+      # @param previous [String] The `previous` cursor from a previous cursor-based response
+      # @param per_page [Integer] How many records to retrieve per page (Paystack defaults to 50)
+      # @param page [Integer] The page to retrieve (Paystack defaults to 1)
+      # @param from [String, Date, Time] A timestamp from which to start listing transfers
+      # @param to [String, Date, Time] A timestamp at which to stop listing transfers
+      # @param recipient [Integer] Filter by the recipient ID
+      # @param status [String] Filter by status. One of: pending, success, failed, otp, abandoned, reversed, blocked, rejected, received.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer/#list
-      def list(query = {})
-        handle_response(@connection.get("/transfer", query))
+      def list(
+        use_cursor: nil,
+        next_cursor: nil,
+        previous: nil,
+        per_page: nil,
+        page: nil,
+        from: nil,
+        to: nil,
+        recipient: nil,
+        status: nil
+      )
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+        validate_allowed_values!(
+          value: status,
+          allowed_values: %w[pending success failed otp abandoned reversed blocked rejected received],
+          name: "status"
+        )
+
+        wire_query = to_wire(
+          {
+            use_cursor:,
+            next_cursor:,
+            previous:,
+            per_page:,
+            page:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to"),
+            recipient:,
+            status:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/transfer", wire_query))
       end
 
-      # Fetch a transfer
-      # @see https://paystack.com/docs/api/transfer/#fetch
-      def fetch(id:)
-        validate_presence!(value: id, name: "transfer id")
-        handle_response(@connection.get("/transfer/#{id}"))
+      # Initiate Transfer.
+      #
+      # Send money to your customers. The transfer's status is `pending` when the OTP requirement is
+      # disabled, and `otp` when an OTP is required (complete it with {#finalize}).
+      #
+      # @param amount [Integer] Amount to transfer in the currency's subunit (kobo for NGN, pesewas for GHS)
+      # @param recipient [String] Code for the transfer recipient (RCP_...)
+      # @param reference [String] A unique identifier for the transfer, so retrying it cannot create a second transfer. Paystack documents 16 to 50 characters of lowercase letters, digits, `-` and `_`.
+      # @param source [String] Where to transfer from. Only "balance" for now.
+      # @param reason [String] The reason for the transfer; it also shows up in the narration of the recipient's credit notification
+      # @param currency [String] The currency of the transfer; Paystack defaults to NGN. One of: NGN, ZAR, KES, GHS.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/#initiate
+      def create(amount:, recipient:, reference:, source:, reason: nil, currency: nil)
+        validate_presence!(value: amount, name: "amount")
+        validate_positive_integer!(value: amount, name: "amount")
+        validate_presence!(value: recipient, name: "recipient")
+        validate_presence!(value: reference, name: "reference")
+        validate_reference_format!(reference: reference, name: "reference")
+        validate_presence!(value: source, name: "source")
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[NGN ZAR KES GHS],
+          name: "currency"
+        )
+
+        wire_body = to_wire(
+          {
+            amount:,
+            recipient:,
+            reference:,
+            source:,
+            reason:,
+            currency:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.post("/transfer", wire_body))
       end
 
-      # Finalize a transfer (OTP)
+      # Finalize Transfer.
+      #
+      # Finalize an initiated transfer that is waiting for an OTP.
+      #
+      # @param transfer_code [String] The transfer code you want to finalize
+      # @param otp [String] OTP sent to the business phone to verify the transfer
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer/#finalize
       def finalize(transfer_code:, otp:)
         validate_presence!(value: transfer_code, name: "transfer_code")
         validate_presence!(value: otp, name: "otp")
-        handle_response(@connection.post("/transfer/finalize_transfer", {transfer_code: transfer_code, otp: otp}))
+
+        wire_body = to_wire({transfer_code:, otp:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/finalize_transfer", wire_body))
+      end
+
+      # Initiate Bulk Transfer.
+      #
+      # Batch multiple transfers in a single request. You need to disable the Transfers OTP
+      # requirement to use this endpoint.
+      #
+      # @param source [String] Where to transfer from. Only "balance" for now.
+      # @param transfers [Array<Hash>] The transfers, each with `amount`, `recipient`, `reference` and optionally `reason`, named as Paystack names them
+      # @param currency [String] The currency of the transfers. One of: NGN, ZAR, KES, GHS.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/#bulk
+      def bulk_create(source:, transfers:, currency: nil)
+        validate_presence!(value: source, name: "source")
+        validate_presence!(value: transfers, name: "transfers")
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[NGN ZAR KES GHS],
+          name: "currency"
+        )
+
+        wire_body = to_wire({source:, transfers:, currency:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/bulk", wire_body))
+      end
+
+      # Fetch Transfer.
+      #
+      # Get details of a transfer on your integration.
+      #
+      # @param id_or_code [String, Integer] The transfer ID or code you want to fetch
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/#fetch
+      def fetch(id_or_code:)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+
+        handle_response(@connection.get("/transfer/#{escape_path(id_or_code, name: "id_or_code")}"))
       end
 
-      # Verify a transfer
+      # Verify Transfer.
+      #
+      # Verify the status of a transfer on your integration.
+      #
+      # @param reference [String] Transfer reference
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer/#verify
       def verify(reference:)
         validate_presence!(value: reference, name: "reference")
-        handle_response(@connection.get("/transfer/verify/#{reference}"))
+
+        handle_response(
+          @connection.get("/transfer/verify/#{escape_path(reference, name: "reference")}")
+        )
+      end
+
+      # Export Transfers.
+      #
+      # Export a list of transfers carried out on your integration. This operation is in Paystack's
+      # OpenAPI spec but not on its docs page; the API answers it (404 "Transfers not found" when
+      # nothing matches).
+      #
+      # @param recipient [String] Export transfers by the recipient code
+      # @param status [String] Export transfers by status. One of: pending, success, failed, otp, abandoned, reversed, blocked, rejected, received.
+      # @param from [String, Date, Time] The start date
+      # @param to [String, Date, Time] The end date
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/
+      def export(recipient: nil, status: nil, from: nil, to: nil)
+        validate_allowed_values!(
+          value: status,
+          allowed_values: %w[pending success failed otp abandoned reversed blocked rejected received],
+          name: "status"
+        )
+
+        wire_query = to_wire(
+          {
+            recipient:,
+            status:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to")
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/transfer/export", wire_query))
+      end
+
+      # Resend OTP for Transfer.
+      #
+      # Generates a new OTP and sends it to the business phone, for when it has trouble receiving one.
+      #
+      # @param transfer_code [String] The transfer code that requires an OTP validation
+      # @param reason [String] The purpose of the OTP. The docs list "resend_otp" and "transfer"; the spec also allows "disable_otp".
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#resend-otp
+      def resend_otp(transfer_code:, reason:)
+        validate_presence!(value: transfer_code, name: "transfer_code")
+        validate_presence!(value: reason, name: "reason")
+        validate_allowed_values!(
+          value: reason,
+          allowed_values: %w[disable_otp resend_otp transfer],
+          name: "reason"
+        )
+
+        wire_body = to_wire({transfer_code:, reason:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/resend_otp", wire_body))
+      end
+
+      # Disable OTP for Transfers.
+      #
+      # Start turning off the OTP requirement so transfers can be completed programmatically.
+      # Paystack sends an OTP to the business phone; confirm with {#finalize_disable_otp}.
+      #
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#disable-otp
+      def disable_otp
+        handle_response(@connection.post("/transfer/disable_otp"))
+      end
+
+      # Finalize Disabling OTP for Transfers.
+      #
+      # Finalize the request to disable OTP on your transfers.
+      #
+      # @param otp [String] OTP sent to the business phone to verify disabling the OTP requirement
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#finalize-disable-otp
+      def finalize_disable_otp(otp:)
+        validate_presence!(value: otp, name: "otp")
+
+        wire_body = to_wire({otp:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/disable_otp_finalize", wire_body))
+      end
+
+      # Enable OTP requirement for Transfers.
+      #
+      # Turn the OTP requirement for transfers back on.
+      #
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#enable-otp
+      def enable_otp
+        handle_response(@connection.post("/transfer/enable_otp"))
       end
     end
   end

data/lib/paystack_sdk/response.rb

@@ -60,6 +60,19 @@ module PaystackSdk
     # @return [Integer] The status code of the API response
     attr_reader :status_code
 
+    # Pagination metadata that Paystack returns with list responses
+    # (e.g. `total`, `page`, `pageCount`, `perPage`).
+    #
+    # @return [Response, nil] The wrapped `meta` object, or nil if the response has none
+    #
+    # @example
+    #   response = transactions.list
+    #   response.meta.total       # => 40
+    #   response.meta.pageCount   # => 2
+    def meta
+      @meta ||= wrap_value(@raw_meta) if @raw_meta
+    end
+
     # Initializes a new Response object
     #
     # @param response [Faraday::Response, Hash, Array] The raw API response or data
@@ -75,10 +88,15 @@ module PaystackSdk
         @api_message = extract_api_message(@body)
         @message = @api_message
         @raw_data = extract_data_from_body(@body)
+        @raw_meta = @body["meta"] if @body.is_a?(Hash) && @body["meta"].is_a?(Hash)
 
         case @status_code
         when 200..299
           @success = true
+        when 429
+          # Rate limiting - raise so callers can back off (the connection
+          # already retries automatically unless max_retries is 0)
+          raise RateLimitError.new(rate_limit_reset(response))
         when 400..499
           # Client errors - return unsuccessful response for user to handle
           @success = false
@@ -86,10 +104,6 @@ module PaystackSdk
 
           # Still raise for authentication issues as these are usually config problems
           raise AuthenticationError.new(@api_message || "Authentication failed") if @status_code == 401
-        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)
@@ -102,6 +116,7 @@ module PaystackSdk
         @error_message = response.error_message
         @api_message = response.api_message
         @raw_data = response.raw_data
+        @raw_meta = response.raw_meta
       else
         @success = true
         @raw_data = response
@@ -123,6 +138,34 @@ module PaystackSdk
       @success
     end
 
+    # Whether this response is a successful payment: the call succeeded and the transaction's
+    # `status` is "success". Paystack's docs say to confirm the amount and currency as well, so
+    # pass the ones you expect and they are compared too.
+    #
+    # @param amount [Integer, nil] The amount (in the currency's subunit) you expect
+    # @param currency [String, nil] The currency you expect, e.g. "GHS"
+    # @return [Boolean]
+    #
+    # @example
+    #   response = client.transactions.verify(reference: ref)
+    #   response.paid?(amount: 5000, currency: "GHS")
+    def paid?(amount: nil, currency: nil)
+      return false unless success? && status?(:success)
+      return false if amount && field(:amount) != amount
+      return false if currency && field(:currency).to_s.upcase != currency.to_s.upcase
+
+      true
+    end
+
+    # Whether the `status` field in the response data equals the given value, e.g.
+    # `response.status?(:send_pin)` on a charge. Paystack names the values; none are assumed here.
+    #
+    # @param value [String, Symbol]
+    # @return [Boolean]
+    def status?(value)
+      field(:status).to_s == value.to_s
+    end
+
     # Check if the response failed
     #
     # @return [Boolean] true if the API request failed
@@ -151,6 +194,14 @@ module PaystackSdk
       @body
     end
 
+    # One field of a Hash response body, whichever way it is keyed; nil otherwise.
+    def field(name)
+      return nil unless @raw_data.is_a?(Hash)
+
+      @raw_data.key?(name) ? @raw_data[name] : @raw_data[name.to_s]
+    end
+    private :field
+
     # Access hash values via methods (dot notation)
     # Allows accessing data attributes directly: response.attribute_name
     #
@@ -181,7 +232,8 @@ module PaystackSdk
         super
     end
 
-    # Access data via hash/array notation
+    # Access data via hash/array notation.
+    # Hash keys can be given as strings or symbols, whichever way the data is keyed.
     #
     # @param key [Object] The key or index to access
     # @return [Object, Response] The value for the given key or index
@@ -189,19 +241,19 @@ module PaystackSdk
       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)
+        actual_key = lookup_key(key)
+        wrap_value(@raw_data[actual_key]) unless actual_key.nil?
       elsif @raw_data.is_a?(Array) && key.is_a?(Integer)
         wrap_value(@raw_data[key])
       end
     end
 
-    # Check if key exists in hash
+    # Check if key exists in hash (as a string or a symbol)
     #
     # @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)
+      @raw_data.is_a?(Hash) && !lookup_key(key).nil?
     end
 
     # Iterate through hash entries or array items
@@ -248,8 +300,35 @@ module PaystackSdk
       end
     end
 
+    protected
+
+    # @return [Hash, nil] The unwrapped `meta` from the response body
+    attr_reader :raw_meta
+
     private
 
+    # Finds the key actually used in the data for a string or symbol lookup.
+    #
+    # @return [Object, nil] The key present in the data, or nil if there is none
+    def lookup_key(key)
+      return key if @raw_data.key?(key)
+
+      alternate = case key
+      when String then key.to_sym
+      when Symbol then key.to_s
+      end
+      alternate if !alternate.nil? && @raw_data.key?(alternate)
+    end
+
+    # Seconds until the rate-limit window ends, from Paystack's
+    # `x-ratelimit-reset` header (nil if absent, not numeric, negative or not finite).
+    def rate_limit_reset(response)
+      seconds = Float(response.headers["x-ratelimit-reset"])
+      (seconds.finite? && seconds >= 0) ? seconds.ceil : nil
+    rescue ArgumentError, TypeError
+      nil
+    end
+
     # Extract the identifier from an error response
     # This looks for common patterns in error messages to find resource identifiers
     #