Module: PaystackSdk::Validations

Included in:
Resources::Base
Defined in:
lib/paystack_sdk/validations.rb

Overview

The Validations module provides shared validation methods for Paystack SDK resources. 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. All validation methods raise specific error types to enable proper error handling in client applications.

“‘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

“‘

Examples:

Usage in a resource class

See Also:

Instance Method Summary collapse

Instance Method Details

#validate_allowed_values!(value:, allowed_values:, name: "Parameter", allow_nil: true) ⇒ Object

Validates that a value is within an allowed set of values.

“‘ruby

validate_allowed_values!(
  value: "allow",
  allowed_values: %w[default allow deny],
  name: "risk_action"
)

“‘

Parameters:

  • value (Object) —

    The value to validate

  • allowed_values (Array) —

    List of allowed values

  • name (String) (defaults to: "Parameter") —

    Name of the parameter for error messages

  • allow_nil (Boolean) (defaults to: true) —

    Whether nil values are allowed

Raises:



137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/paystack_sdk/validations.rb', line 137

def validate_allowed_values!(value:, allowed_values:, name: "Parameter", allow_nil: true)
  if value.nil?
    raise PaystackSdk::MissingParamError.new(name) unless allow_nil

    return
  end

  return if allowed_values.include?(value)

  allowed_list = allowed_values.join(", ")
  raise PaystackSdk::InvalidValueError.new(name, "must be one of: #{allowed_list}")
end

#validate_currency!(currency:, name: "Currency", allow_nil: true) ⇒ Object

Validates a currency code format.

Parameters:

  • currency (String) —

    The currency code to validate

  • name (String) (defaults to: "Currency") —

    Name of the parameter for error messages

  • allow_nil (Boolean) (defaults to: true) —

    Whether nil values are allowed

Raises:



174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/paystack_sdk/validations.rb', line 174

def validate_currency!(currency:, name: "Currency", allow_nil: true)
  if currency.nil?
    raise PaystackSdk::MissingParamError.new(name) unless allow_nil

    return
  end

  return if currency.to_s.match?(/\A[A-Z]{3}\z/)

  raise PaystackSdk::InvalidFormatError.new(name, "3-letter ISO code (e.g., NGN, USD, GHS)")
end

#validate_date_format!(date_str:, name: "Date", allow_nil: true) ⇒ Object

Validates a date string format.

Parameters:

  • date_str (String) —

    The date string to validate

  • name (String) (defaults to: "Date") —

    Name of the parameter for error messages

  • allow_nil (Boolean) (defaults to: true) —

    Whether nil values are allowed

Raises:



106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/paystack_sdk/validations.rb', line 106

def validate_date_format!(date_str:, name: "Date", allow_nil: true)
  if date_str.nil?
    raise PaystackSdk::MissingParamError.new(name) unless allow_nil

    return
  end

  begin
    Date.parse(date_str.to_s)
  rescue Date::Error
    raise PaystackSdk::InvalidFormatError.new(name, "YYYY-MM-DD or ISO8601")
  end
end

#validate_email!(email:, name: "Email", allow_nil: false) ⇒ Object

Validates an email format.

Parameters:

  • email (String) —

    The email to validate

  • name (String) (defaults to: "Email") —

    Name of the parameter for error messages

  • allow_nil (Boolean) (defaults to: false) —

    Whether nil values are allowed

Raises:



156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/paystack_sdk/validations.rb', line 156

def validate_email!(email:, name: "Email", allow_nil: false)
  if email.nil?
    raise PaystackSdk::MissingParamError.new(name) unless allow_nil

    return
  end

  return if email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)

  raise PaystackSdk::InvalidFormatError.new(name, "valid email address")
end

#validate_fields!(payload:, validations:) ⇒ Object

Validates multiple fields at once.

“‘ruby

validate_fields!(
  payload: params,
  validations: {
    email: { type: :email, required: true },
    amount: { type: :positive_integer, required: true },
    currency: { type: :currency, required: false },
    reference: { type: :reference, required: false }
  }
)

“‘

Parameters:

  • payload (Hash) —

    The payload containing fields to validate

  • validations (Hash) —

    Mapping of field names to validation options

Raises:



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/paystack_sdk/validations.rb', line 204

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?

  # Then validate each field
  validations.each do |field, options|
    value = payload[field] || payload[field.to_s]
    next if value.nil? && !options[:required]

    case options[:type]
    when :email
      validate_email!(email: value, name: field.to_s.capitalize, allow_nil: !options[:required])
    when :positive_integer
      validate_positive_integer!(value: value, name: field.to_s, allow_nil: !options[:required])
    when :reference
      validate_reference_format!(reference: value, name: field.to_s) if value
    when :date
      validate_date_format!(date_str: value, name: field.to_s, allow_nil: !options[:required])
    when :currency
      validate_currency!(currency: value, name: field.to_s, allow_nil: !options[:required])
    when :inclusion
      if value
        validate_allowed_values!(
          value: value,
          allowed_values: options[:allowed_values],
          name: field.to_s,
          allow_nil: !options[:required]
        )
      end
    when :string
      validate_presence!(value: value, name: field.to_s) if !options[:allow_nil] && options[:required]
    end
  end
end

#validate_hash!(input:, name: "Payload") ⇒ Object

Validates that input is a hash.

Parameters:

  • input (Object) —

    The input to validate

  • name (String) (defaults to: "Payload") —

    Name of the parameter for error messages

Raises:



39
40
41
42
43
 
# File 'lib/paystack_sdk/validations.rb', line 39

def validate_hash!(input:, name: "Payload")
  return if input.is_a?(Hash)

  raise PaystackSdk::InvalidFormatError.new(name, "Hash")
end

#validate_positive_integer!(value:, name: "Parameter", allow_nil: true) ⇒ Object

Validates that a number is a positive integer.

Parameters:

  • value (Object) —

    The value to validate

  • name (String) (defaults to: "Parameter") —

    Name of the parameter for error messages

  • allow_nil (Boolean) (defaults to: true) —

    Whether nil values are allowed

Raises:



80
81
82
83
84
85
86
 
# File 'lib/paystack_sdk/validations.rb', line 80

def validate_positive_integer!(value:, name: "Parameter", allow_nil: true)
  if value.nil?
    raise PaystackSdk::MissingParamError.new(name) unless allow_nil
  elsif !value.is_a?(Integer) || value < 1
    raise PaystackSdk::InvalidValueError.new(name, "must be a positive integer")
  end
end

#validate_presence!(value:, name: "Parameter") ⇒ Object

Validates that a value is present (not nil or empty).

Parameters:

  • value (Object) —

    The value to validate

  • name (String) (defaults to: "Parameter") —

    Name of the parameter for error messages

Raises:



67
68
69
70
71
 
# File 'lib/paystack_sdk/validations.rb', line 67

def validate_presence!(value:, name: "Parameter")
  if value.nil? || (value.respond_to?(:empty?) && value.empty?)
    raise PaystackSdk::MissingParamError.new(name)
  end
end

#validate_reference_format!(reference:, name: "Reference") ⇒ Object

Validates a transaction reference format.

Parameters:

  • reference (String) —

    The reference to validate

  • name (String) (defaults to: "Reference") —

    Name of the parameter for error messages

Raises:



93
94
95
96
97
 
# File 'lib/paystack_sdk/validations.rb', line 93

def validate_reference_format!(reference:, name: "Reference")
  return if reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)

  raise PaystackSdk::InvalidFormatError.new(name, "alphanumeric characters and the following: -, ., =")
end

#validate_required_params!(payload:, required_params:, operation_name: "Operation") ⇒ Object

Validates that required parameters are present in a payload.

Parameters:

  • payload (Hash) —

    The payload to validate

  • required_params (Array<Symbol>) —

    List of required parameter keys

  • operation_name (String) (defaults to: "Operation") —

    Name of the operation for error messages

Raises:



51
52
53
54
55
56
57
58
59
60
 
# File 'lib/paystack_sdk/validations.rb', line 51

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

  return if missing_params.empty?

  param = missing_params.first
  raise PaystackSdk::MissingParamError.new(param)
end