Class: CreateSend::CreateSend

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/createsend/createsend.rb

Overview

Provides high level CreateSend functionality/data you’ll probably need.

Direct Known Subclasses

Administrator, Subscriber

Constant Summary collapse

@@base_uri = 
"https://api.createsend.com/api/v3"
@@oauth_base_uri = 
"https://api.createsend.com/oauth"
@@oauth_token_uri = 
"#{@@oauth_base_uri}/token"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ CreateSend

Returns a new instance of CreateSend.



91
92
93
94
95
 
# File 'lib/createsend/createsend.rb', line 91

def initialize(*args)
  if args.size > 0
    auth args.first # Expect auth details as first argument
  end
end

Instance Attribute Details

#auth_details ⇒ Object (readonly)

Returns the value of attribute auth_details.



45
46
47
 
# File 'lib/createsend/createsend.rb', line 45

def auth_details
  @auth_details
end

Class Method Details

.authorize_url(client_id, redirect_uri, scope, state = nil) ⇒ Object

Get the authorization URL for your application, given the application’s client_id, redirect_uri, scope, and optional state data.



49
50
51
52
53
54
55
 
# File 'lib/createsend/createsend.rb', line 49

def self.authorize_url(client_id, redirect_uri, scope, state=nil)
  qs = "client_id=#{CGI.escape(client_id.to_s)}"
  qs << "&redirect_uri=#{CGI.escape(redirect_uri.to_s)}"
  qs << "&scope=#{CGI.escape(scope.to_s)}"
  qs << "&state=#{CGI.escape(state.to_s)}" if state
  "#{@@oauth_base_uri}?#{qs}"
end

.exchange_token(client_id, client_secret, redirect_uri, code) ⇒ Object

Exchange a provided OAuth code for an OAuth access token, ‘expires in’ value, and refresh token.



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/createsend/createsend.rb', line 59

def self.exchange_token(client_id, client_secret, redirect_uri, code)
  body = "grant_type=authorization_code"
  body << "&client_id=#{CGI.escape(client_id.to_s)}"
  body << "&client_secret=#{CGI.escape(client_secret.to_s)}"
  body << "&redirect_uri=#{CGI.escape(redirect_uri.to_s)}"
  body << "&code=#{CGI.escape(code.to_s)}"
  options = {:body => body}
  response = HTTParty.post(@@oauth_token_uri, options)
  if response.has_key? 'error' and response.has_key? 'error_description'
    err = "Error exchanging code for access token: "
    err << "#{response['error']} - #{response['error_description']}"
    raise err
  end
  r = Hashie::Mash.new(response)
  [r.access_token, r.expires_in, r.refresh_token]
end

.refresh_access_token(refresh_token) ⇒ Object

Refresh an OAuth access token, given an OAuth refresh token. Returns a new access token, ‘expires in’ value, and refresh token.



78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/createsend/createsend.rb', line 78

def self.refresh_access_token(refresh_token)
  options = {
    :body => "grant_type=refresh_token&refresh_token=#{refresh_token}" }
  response = HTTParty.post(@@oauth_token_uri, options)
  if response.has_key? 'error' and response.has_key? 'error_description'
    err = "Error refreshing access token: "
    err << "#{response['error']} - #{response['error_description']}"
    raise err
  end
  r = Hashie::Mash.new(response)
  [r.access_token, r.expires_in, r.refresh_token]
end

Instance Method Details

#add_auth_details_to_options(args) ⇒ Object 



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/createsend/createsend.rb', line 210

def add_auth_details_to_options(args)
  if @auth_details
    options = {}
    if args.size > 1
      options = args[1]
    end
    if @auth_details.has_key? :access_token
      options[:headers] = {
        "Authorization" => "Bearer #{@auth_details[:access_token]}" }
    elsif @auth_details.has_key? :api_key
      if not options.has_key? :basic_auth
        options[:basic_auth] = {
          :username => @auth_details[:api_key], :password => 'x' }
      end
    end
    args[1] = options
  end
  args
end

#administrators ⇒ Object

Gets the administrators for the account.



168
169
170
171
 
# File 'lib/createsend/createsend.rb', line 168

def administrators
  response = get('/admins.json')
  response.map{|item| Hashie::Mash.new(item)}
end

#apikey(site_url, username, password) ⇒ Object

Gets your CreateSend API key, given your site url, username and password.



128
129
130
131
132
133
134
135
 
# File 'lib/createsend/createsend.rb', line 128

def apikey(site_url, username, password)
  site_url = CGI.escape(site_url)
  options = {:basic_auth => {:username => username, :password => password}}
  response = get("/apikey.json?SiteUrl=#{site_url}", options)
  result = Hashie::Mash.new(response)
  auth({:api_key => result.ApiKey}) if not @auth_details
  result
end

#auth(auth_details) ⇒ Object

Authenticate using either OAuth or an API key.



107
108
109
 
# File 'lib/createsend/createsend.rb', line 107

def auth(auth_details)
  @auth_details = auth_details
end

#billing_details ⇒ Object

Get your billing details.



144
145
146
147
 
# File 'lib/createsend/createsend.rb', line 144

def billing_details
  response = get('/billingdetails.json')
  Hashie::Mash.new(response)
end

#clients ⇒ Object

Gets your clients.



138
139
140
141
 
# File 'lib/createsend/createsend.rb', line 138

def clients
  response = get('/clients.json')
  response.map{|item| Hashie::Mash.new(item)}
end

#countries ⇒ Object

Gets valid countries.



150
151
152
153
 
# File 'lib/createsend/createsend.rb', line 150

def countries
  response = get('/countries.json')
  response.parsed_response
end

#delete(*args) ⇒ Object Also known as: cs_delete 



204
205
206
207
 
# File 'lib/createsend/createsend.rb', line 204

def delete(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.delete(*args)
end

#get(*args) ⇒ Object Also known as: cs_get 



186
187
188
189
 
# File 'lib/createsend/createsend.rb', line 186

def get(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.get(*args)
end

#get_primary_contact ⇒ Object

Gets the primary contact for the account.



174
175
176
177
 
# File 'lib/createsend/createsend.rb', line 174

def get_primary_contact
  response = get('/primarycontact.json')
  Hashie::Mash.new(response)
end

#handle_response(response) ⇒ Object

:nodoc:



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/createsend/createsend.rb', line 230

def handle_response(response) # :nodoc:
  case response.code
  when 400
    raise BadRequest.new(Hashie::Mash.new response)
  when 401
    data = Hashie::Mash.new(response)
    case data.Code
    when 120
      raise InvalidOAuthToken.new data
    when 121
      raise ExpiredOAuthToken.new data
    when 122
      raise RevokedOAuthToken.new data
    else
      raise Unauthorized.new data
    end
  when 404
    raise NotFound.new
  when 400...500
    raise ClientError.new
  when 500...600
    raise ServerError.new
  else
    response
  end
end

#post(*args) ⇒ Object Also known as: cs_post 



192
193
194
195
 
# File 'lib/createsend/createsend.rb', line 192

def post(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.post(*args)
end

#put(*args) ⇒ Object Also known as: cs_put 



198
199
200
201
 
# File 'lib/createsend/createsend.rb', line 198

def put(*args)
  args = add_auth_details_to_options(args)
  handle_response CreateSend.put(*args)
end

#refresh_token ⇒ Object

Refresh the current OAuth token using the current refresh token.



112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/createsend/createsend.rb', line 112

def refresh_token
  if not @auth_details or
    not @auth_details.has_key? :refresh_token or
    not @auth_details[:refresh_token]
    raise '@auth_details[:refresh_token] does not contain a refresh token.'
  end

  access_token, expires_in, refresh_token =
    self.class.refresh_access_token @auth_details[:refresh_token]
  auth({
    :access_token => access_token,
    :refresh_token => refresh_token})
  [access_token, expires_in, refresh_token]
end

#set_primary_contact(email) ⇒ Object

Set the primary contect for the account.



180
181
182
183
184
 
# File 'lib/createsend/createsend.rb', line 180

def set_primary_contact(email)
  options = { :query => { :email => email } }
  response = put("/primarycontact.json", options)
  Hashie::Mash.new(response)
end

#systemdate ⇒ Object

Gets the current date in your account’s timezone.



156
157
158
159
 
# File 'lib/createsend/createsend.rb', line 156

def systemdate
  response = get('/systemdate.json')
  Hashie::Mash.new(response)
end

#timezones ⇒ Object

Gets valid timezones.



162
163
164
165
 
# File 'lib/createsend/createsend.rb', line 162

def timezones
  response = get('/timezones.json')
  response.parsed_response
end