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:



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

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

  unless allowed_values.include?(value)
    allowed_list = allowed_values.join(", ")
    raise PaystackSdk::InvalidValueError.new(name, "must be one of: #{allowed_list}")
  end
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:



171
172
173
174
175
176
177
178
179
180
 
# File 'lib/paystack_sdk/validations.rb', line 171

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

  unless currency.to_s.match?(/\A[A-Z]{3}\z/)
    raise PaystackSdk::InvalidFormatError.new(name, "3-letter ISO code (e.g., NGN, USD, GHS)")
  end
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
 
# 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:



154
155
156
157
158
159
160
161
162
163
 
# File 'lib/paystack_sdk/validations.rb', line 154

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

  unless email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
    raise PaystackSdk::InvalidFormatError.new(name, "valid email address")
  end
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:



200
201
202
203
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
 
# File 'lib/paystack_sdk/validations.rb', line 200

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")
  unless input.is_a?(Hash)
    raise PaystackSdk::InvalidFormatError.new(name, "Hash")
  end
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")
  unless reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)
    raise PaystackSdk::InvalidFormatError.new(name, "alphanumeric characters and the following: -, ., =")
  end
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

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