Class: PayTrace::API::Request

Inherits:
Object
  • Object
show all
Defined in:
lib/paytrace/api/request.rb

Overview

An object representing an API request to be sent using a PayTrace::API::Gateway object

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Request

Initializes a new Request object



10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
# File 'lib/paytrace/api/request.rb', line 10

def initialize
  @field_delim = "|"
  @multi_field_delim = "+"
  @value_delim = "~"
  @multi_value_delim = "="

  @params= {
    user_name: [PayTrace.configuration.user_name],
    password: [PayTrace.configuration.password],
    terms: ["Y"]
  }

  @discretionary_data = {}
end

Instance Attribute Details

#discretionary_data ⇒ Object (readonly)

:nodoc:



6
7
8
 
# File 'lib/paytrace/api/request.rb', line 6

def discretionary_data
  @discretionary_data
end

#field_delim ⇒ Object (readonly)

:nodoc:



6
7
8
 
# File 'lib/paytrace/api/request.rb', line 6

def field_delim
  @field_delim
end

#params ⇒ Object (readonly)

:nodoc:



6
7
8
 
# File 'lib/paytrace/api/request.rb', line 6

def params
  @params
end

#value_delim ⇒ Object (readonly)

:nodoc:



6
7
8
 
# File 'lib/paytrace/api/request.rb', line 6

def value_delim
  @value_delim
end

Class Method Details

.process_param_list(key_list, params, &block) ⇒ Object

takes a list of permitted keys and a params hash, and returns any missing or extra params, optionally calling a supplied block once per key



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/paytrace/api/request.rb', line 138

def self.process_param_list(key_list, params, &block)
  if params.is_a?(Hash)
    accessor = :[]
    track_params = true
  else
    accessor = :send
    track_params = false
  end
  params_remaining = params.dup if track_params

  remaining = key_list.dup
  key_list.each do |key|
    request_variable, arg_name = key # de-alias the name, if it's aliased
    arg_name ||= request_variable # just use the same name for both, if not

    value = params.send(accessor, arg_name) # this allows us to treat hashes and objects the same
    yield request_variable, arg_name, value if block_given?
    remaining.delete(key) if value
    params_remaining.delete(arg_name) if track_params
  end

  return (remaining.map {|req,arg| arg || req}), (track_params ? params_remaining : nil)
end

Instance Method Details

#set_discretionary(key, value = nil) ⇒ Object

Sets discretionary data keys and values

  • :key – the name of the setting

  • :value – the value of the setting

Note: you can bulk-set discretionary data by simply passing in a hash as the “key”



47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/paytrace/api/request.rb', line 47

def set_discretionary(key, value = nil)
  if key.is_a?(Hash)
    ddata_hash = key
    ddata_hash.keys.each do |inner_key|
      inner_value = ddata_hash[inner_key]
      @discretionary_data[inner_key] = inner_value unless inner_value.nil?
    end
  elsif key.is_a?(Symbol)
    @discretionary_data[key] = value unless value.nil?
  end
end

#set_multivalue(param_name, items = {}) ⇒ Object

Sets multiple parameters with the same name using the custom delimiter

  • param_name – the name of the “top level” setting

  • items – a hash of “second level” settings



76
77
78
79
80
81
82
83
84
85
 
# File 'lib/paytrace/api/request.rb', line 76

def set_multivalue(param_name, items = {})
  result = (items.map do |k,v|
    validate_param!(k, v)
    "#{PayTrace::API.fields[k]}#{@multi_value_delim}#{v}"
  end.join(@multi_field_delim))

  set_param(param_name, result)

  result
end

#set_param(key, value = nil) ⇒ Object

Sets a single request parameters

  • key – the name of the setting

  • value – the value of the setting

Note: you can pass in an object that responds to set_request as the value, and this will invoke set_request on it, with this request object as the parameter. Also, any value named :discretionary_data that is set will be set in the discretionary hash, not the regular params hash.



92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/paytrace/api/request.rb', line 92

def set_param(key, value = nil)
  validate_param!(key, value)

  if value.respond_to?(:set_request)
    value.set_request(self)
  elsif key == :discretionary_data
    set_discretionary(value)
  elsif value != nil
    @params[key] ||= []

    @params[key] << value
  end
end

#set_params(params, required = [], optional = []) ⇒ Object

Sets multiple parameters at once

  • :params – the hash or object to fetch the parameters from

  • :required – an array of required key names to extract from the params object

Note: the values in :keys can also include arrays of two values (techincally, a tuple). The sub-array contains the name of the field that will be used in the request, and the name of the field in the params. This allows more succinct parameter names; e.g. :address instead of :billing_address. Example:

#
# note the nested array; this will send the field :billing_address,
# but uses the argument :address as the argument name
#
set_params([
    :foo,
    [:billing_address, :address]
  ], params)

Raises:



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/paytrace/api/request.rb', line 120

def set_params(params, required = [], optional = [])
  required_remaining, params_remaining = Request.process_param_list(required, params) do |request_variable, arg_name, value|
    set_param(request_variable, value)
  end

  # if we're missing *required* parameters, fail...
  raise PayTrace::Exceptions::ValidationError.new("Missing the following required parameters: #{required_remaining.to_s}") if required_remaining.any?

  optional_remaining, params_remaining = Request.process_param_list(optional, params_remaining) do |request_variable, arg_name, value|
    set_param(request_variable, value)
  end

  # if we have any EXTRA parameters, fail...
  raise PayTrace::Exceptions::ValidationError.new("The following parameters are unknown: #{params_remaining.to_s}") if params_remaining && params_remaining.any?
end

#to_parms_string ⇒ Object

Returns the formatted URL that this request will send



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/paytrace/api/request.rb', line 26

def to_parms_string()
  raw_request = @params.map do |k,items|
    items.map do |item|
      "#{PayTrace::API.fields[k]}#{@value_delim}#{item}"
    end
  end.join(@field_delim) << @field_delim

  if @discretionary_data.any?
    raw_request << @discretionary_data.map do |k,v|
      "#{k}#{@value_delim}#{v}"
    end.join(@field_delim) << @field_delim
  end

  raw_request
end

#valid_param?(key, value) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


60
61
62
63
64
65
66
 
# File 'lib/paytrace/api/request.rb', line 60

def valid_param?(key, value)
  if key == :discretionary_data
    value.is_a?(Hash) || value.nil? # any discretionary data that's a hash or nil should be passed
  else
    PayTrace::API.fields.has_key?(key) || value.nil? || value.respond_to?(:set_request)
  end
end

#validate_param!(k, v) ⇒ Object

Raises:



68
69
70
 
# File 'lib/paytrace/api/request.rb', line 68

def validate_param!(k, v)
  raise PayTrace::Exceptions::ValidationError.new("Unknown field '#{k}' (value: #{v})") unless valid_param?(k,v)
end