sailthru-client 1.02 → 1.03

data/README.md

@@ -1,4 +1,180 @@
-# A simple client library to remotely access the Sailthru REST API.
+sailthru-ruby-client
+====================
 
-## Installing from rubygems.org (Tested with Ruby 1.8.7)
+A simple client library to remotely access the `Sailthru REST API` as per [http://docs.sailthru.com/api](http://docs.sailthru.com/api)
+
+It can make requests to following [API calls](http://docs.sailthru.com/api):
+
+* [email](http://docs.sailthru.com/api/email)
+* [send](http://docs.sailthru.com/api/send)
+* [blast](http://docs.sailthru.com/api/blast)
+* [template](http://docs.sailthru.com/api/template)
+* [list](http://docs.sailthru.com/api/list)
+* [contacts](http://docs.sailthru.com/api/contacts)
+* [content](http://docs.sailthru.com/api/content)
+* [alert](http://docs.sailthru.com/api/alert)
+* [stats](http://docs.sailthru.com/api/stats)
+* [purchase](http://docs.sailthru.com/api/purchase)
+* [horizon](http://docs.sailthru.com/api/horizon)
+
+### Installing from rubygems.org (Tested with Ruby 1.8.7)
     $ gem install sailthru-client
+
+Examples
+--------
+	require 'lib/sailthru'
+
+ 	api_key = "api_key";
+    api_secret = 'secret';
+    api_url = "https://api.sailthru.com";
+ 	sailthru = Sailthru::SailthruClient.new(api_key, api_secret, api_url)
+
+### [send](http://docs.sailthru.com/api/send)
+
+    #send
+    template_name = 'my-template'
+    email = 'praj@sailthru.com'
+    vars = {'name' => 'Prajwal Tuladhar', "myvar" => [1111,2,3]}
+    options = {'test' => 1}
+    schedule_time = '+3 hours'
+    response = sailthru.send(template_name, email, vars, options, schedule_time)
+
+    #get send
+    send_id = '6363'
+    response = sailthru.get_send(send_id)
+
+    #cancel send
+    send_id = '236236sbs'
+    response = sailthru.cancel_send(send_id)
+
+    #multi send
+    template_name = 'my-template'
+    emails = 'praj@sailthru.com, ian@sailthru.com'
+    vars = {'name' => 'Prajwal Tuladhar', "myvar" => [1111,2,3]}
+    options = {'test' => 1}
+    response = sailthru.multi_send(template_name, emails, vars, options)
+
+### [email](http://docs.sailthru.com/api/email)
+
+    #get email
+    email = 'praj@sailthru.com'
+    response = sailthru.get_email(email)
+
+    #set email
+    email = 'praj@sailthru.com'
+    response = sailthru.set_email(email)
+
+### [blast](http://docs.sailthru.com/api/blast)
+
+	# schedule blast
+	blast_name = 'My blast name'
+	template = 'my-template'
+	schedule_time = '+5 hours'
+	from_name = 'prajwal tuladhar'
+	from_email = 'praj@sailthru.com'
+	subject = 'What's up!'
+	html = '<p>Lorem ispum is great</p>'
+	text = 'Lorem ispum is great'
+	response = sailthru.schedule_blast(blast_name, template, schedule_time, from_name, from_email, subject, html, text)
+
+	#update blast
+	blast_id = 7886
+	name = 'prajwal tuladhar 64'
+	response = sailthru.update_blast(blast_id, name = name)
+
+	#get blast info
+	blast_id = 7886
+	response = sailthru.get_blast(blast_id)
+
+	#cancel blast
+	blast_id = 7886
+	response = sailthru.cancel_blast(blast_id)
+
+	#delete blast
+	blast_id = 7886
+	response = sailthru.delete_blast(blast_id)
+
+
+### [list](http://docs.sailthru.com/api/list)
+
+	#save list
+	list_name = 'my-list'
+	emails = ['praj@sailthru.com', 'ian@sailthru.com']
+	response = sailthru.save_list(list_name, emails)
+
+	#download /get list
+	list_name = 'my-list'
+	format = 'json'
+	response = sailthru.get_list(list_name, format)
+
+	#delete list
+	list_name = 'my-list'
+	response = sailthru.delete_list(list_name)
+
+### [contacts](http://docs.sailthru.com/api/contacts)
+
+	#import contacts
+	email = 'infynyxx@aol.com'
+	password = 'my super awesome password'
+	with_names = true
+	response = sailthru.import_contacts(email, password, with_names)
+
+### [content](http://docs.sailthru.com/api/content)
+
+	#push content
+	title = 'hello world'
+    url = 'http://example.com/product-url'
+    response = sailthru.push_content(title, url)
+
+    #another push content exammple
+    title = 'hello world'
+    url = 'http://example.com/product-url'
+    tags = ["blue", "red", "green"]
+    vars = {'vars' => ['price' => 17299]}
+    date = nil
+	response = sailthru.push_content(title, url, date, tags = tags, vars = vars)
+
+### [alert](http://docs.sailthru.com/api/alert)
+
+	#get alert info
+	email = 'praj@sailthru.com'
+	response = sailthru.get_alert(email)
+
+	#save alert
+	email = 'praj@sailthru.com'
+	type = 'daily'
+	_when = '+5 hours'
+	extras = {'tags' => ['red', 'blue'], 'match' => {'type' => 'yellow'}}
+	response = sailthru.save_alert(email, type, _when, extras)
+
+	#delete alert
+	email = 'praj@sailthru.com'
+	alert_id = '4d4b17a36763d930210007ba'
+	response = sailthru.delete_alert(email, alert_id)
+
+### [purchase](http://docs.sailthru.com/api/purchase)
+
+	#purchase API call
+	email = 'praj@sailthru.com'
+	items = [{"price"=>1099, "qty"=>22, "title"=>"High-Impact Water Bottle", "url"=>"http://example.com/234/high-impact-water-bottle", "id"=>"234"}, {"price"=>500, "qty"=>2, "title"=>"Lorem Ispum", "url"=>"http://example.com/2304/lorem-ispum", "id"=>"2304"}]
+	response = sailthru.purchase(email, items)
+
+### [stats](http://docs.sailthru.com/api/stats)
+
+	#stats list
+	response = sailthru.stats_list()
+
+	#stats blast
+	blast_id = 42382
+	response = sailthru.stats_blast(blast_id)
+
+### [horizon](http://docs.sailthru.com/api/horizon)
+
+	#get horizon user info
+	email = 'praj@sailthru.com'
+	response = sailthru.get_horizon(email)
+
+	#set horizon data
+	email = 'praj@sailthru.com'
+	tags = ['red', 'blue']
+	response = sailthru.set_horizon(email, tags)

data/lib/sailthru.rb

@@ -7,7 +7,7 @@ require 'md5'
 
 module Sailthru
 
-  Version = VERSION = '1.02'
+  Version = VERSION = '1.03'
 
   class SailthruClientException < Exception
   end
@@ -133,7 +133,7 @@ module Sailthru
       if vars.length > 0
         post[:vars] = vars
       end
-      
+
       if schedule_time != nil
           post[:schedule_time] = schedule_time
       end
@@ -169,7 +169,7 @@ module Sailthru
       self.api_get(:send, {:send_id => send_id.to_s})
     end
 
-    
+
     def cancel_send(send_id)
       self.api_delete(:send, {:send_id => send_id.to_s})
     end
@@ -198,18 +198,78 @@ module Sailthru
       post[:subject] = subject
       post[:content_html] = content_html
       post[:content_text] = content_text
-      self.api_post(:blast, post)
+      api_post(:blast, post)
+    end
+
+
+    # params
+    #   blast_id, Fixnum | String
+    #   name, String
+    #   list, String
+    #   schedule_time, String
+    #   from_name, String
+    #   from_email, String
+    #   subject, String
+    #   content_html, String
+    #   content_text, String
+    #   options, hash
+    #
+    # updates existing blast
+    def update_blast(blast_id, name = nil, list = nil, schedule_time = nil, from_name = nil, from_email = nil, subject = nil, content_html = nil, content_text = nil, options = {})
+      data = options ? options : {}
+      data[:blast_id] = blast_id
+      if name != nil
+        data[:name] = name
+      end
+      if list !=  nil
+        data[:list] = list
+      end
+      if schedule_time != nil
+        data[:schedule_time] = schedule_time
+      end
+      if from_name != nil
+        data[:from_name] = from_name
+      end
+      if from_email != nil
+        data[:from_email] = from_email
+      end
+      if subject != nil
+        data[:subject] = subject
+      end
+      if content_html != nil
+        data[:content_html] = content_html
+      end
+      if content_text != nil
+        data[:content_text] = content_text
+      end
+      api_post(:blast, data)
     end
 
 
     # params:
-    #   blast_id, Fixnum
+    #   blast_id, Fixnum | String
     # returns:
     #   Hash, response data from server
     #
     # Get information on a previously scheduled email blast
     def get_blast(blast_id)
-      self.api_get(:blast, {:blast_id => blast_id.to_s})
+      api_get(:blast, {:blast_id => blast_id.to_s})
+    end
+
+    # params:
+    #   blast_id, Fixnum | String
+    #
+    # Cancel a scheduled Blast
+    def cancel_blast(blast_id)
+      api_post(:blast, {:blast_id => blast_id, :schedule_time => ''})
+    end
+
+    # params:
+    #   blast_id, Fixnum | String
+    #
+    # Delete a Blast
+    def delete_blast(blast_id)
+      api_delete(:blast, {:blast_id => blast_id})
     end
 
     # params:
@@ -219,7 +279,7 @@ module Sailthru
     #
     # Return information about an email address, including replacement vars and lists.
     def get_email(email)
-      self.api_get(:email, {:email => email})
+      api_get(:email, {:email => email})
     end
 
     # params:
@@ -317,7 +377,7 @@ module Sailthru
     def purchase(email, items, incomplete = nil, message_id = nil)
       data = {}
       data[:email] = email
-      
+
       if verify_purchase_items(items)
         data[:items] = items
       end
@@ -325,13 +385,15 @@ module Sailthru
       if incomplete != nil
         data[:incomplete] = incomplete.to_i
       end
-      
+
       if message_id != nil
         data[:message_id] = message_id
       end
       api_post(:purchase, data)
     end
 
+
+    # <b>DEPRECATED:</b> Please use either stats_list or stats_blast
     # params:
     #   stat, String
     #
@@ -339,12 +401,190 @@ module Sailthru
     #   hash, response from server
     # Request various stats from Sailthru.
     def get_stats(stat)
+      warn "[DEPRECATION] `get_stats` is deprecated. Please use `stats_list` and `stats_blast` instead"
       api_get(:stats, {:stat => stat})
     end
 
 
+    # params
+    #   list, String
+    #   date, String
+    #
+    # returns:
+    #   hash, response from server
+    # Retrieve information about your subscriber counts on a particular list, on a particular day.
+    def stats_list(list = nil, date = nil)
+      data = {}
+      if list != nil
+        data[:list] = list
+      end
+      if date != nil
+        data[:date] = date
+      end
+      data[:stat] = 'list'
+
+      stats(data)
+    end
+
+
+    # params
+    #   blast_id, String
+    #   start_date, String
+    #   end_date, String
+    #   options, Hash
+    #
+    # returns:
+    #   hash, response from server
+    # Retrieve information about a particular blast or aggregated information from all of blasts over a specified date range
+    def stats_blast(blast_id = nil, start_date = nil, end_date = nil, options = {})
+      data = options
+      if blast_id != nil
+        data[:blast_id] = blast_id
+      end
+      if start_date != nil
+        data[:start_date] = start_date
+      end
+      if end_date != nil
+        data[:end_date] = end_date
+      end
+      data[:stat] = 'blast'
+      stats(data)
+    end
+
+
+    # params
+    #   title, String
+    #   url, String
+    #   date, String
+    #   tags, Array or Comma separated string
+    #   vars, Hash
+    #
+    # Push a new piece of content to Sailthru, triggering any applicable alerts.
+    # http://docs.sailthru.com/api/content
+    def push_content(title, url, date = nil, tags = nil, vars = {})
+      data = {}
+      data[:title] = title
+      data[:url] = url
+      if date != nil
+        data[:date] = date
+      end
+      if tags != nil
+        if tags.class == Array
+          tags = tags.join(',')
+        end
+        data[:tags] = tags
+      end
+      if vars.length > 0
+        data[:vars] = vars
+      end
+      api_post(:content, data)
+    end
+
+    # params
+    #   list, String
+    #   format, String
+    #
+    # Download a list. Obviously, this can potentially be a very large download.
+    # 'txt' is default format since, its more compact as compare to others
+    def get_list(list, format = 'txt')
+      return api_get(:list, {:list => list, :format => format})
+    end
+
+
+    # params
+    #   list, String
+    #   emails, String | Array
+    # Upload a list. The list import job is queued and will happen shortly after the API request.
+    def save_list(list, emails)
+      data = {}
+      data[:list] = list
+      data[:emails] = (emails.class == Array) ? emails.join(',') : emails
+     return api_post(:list, data)
+    end
+
+
+    # params
+    #   list, String
+    #
+    # Deletes a list
+    def delete_list(list)
+      api_delete(:list, {:list => list})
+    end
+
+    # params
+    #   email, String
+    #   hid_only, Boolean
+    #
+    # gets horizon data
+    def get_horizon(email, hid_only = false)
+      data = {}
+      data[:email] = email
+     if hid_only == true
+        data[:hid_only] = 1
+     end
+      api_get(:horizon, data)
+    end
+
+
+    # params
+    #   email, String
+    #   tags, String | Array
+    #
+    # sets horizon data
+    def set_horizon(email, tags)
+      data = {}
+      data[
+      :email] = email
+      data[:tags] = (tags.class == Array) ? tags.join(',') : tags
+      api_post(:horizon, data)
+    end
+
+    # params
+    #   email, String
+    #
+    # get user alert data
+    def get_alert(email)
+      api_get(:alert, {:email => email})
+    end
+
+    # params
+    #   email, String
+    #   type, String
+    #   template, String
+    #   _when, String
+    #   options, hash
+    #
+    # Add a new alert to a user. You can add either a realtime or a summary alert (daily/weekly).
+    # _when is only required when alert type is weekly or daily
+    def save_alert(email, type, template, _when = nil, options = {})
+      data = options
+      data[:email] = email
+      data[:type] = type
+      data[:template] = template
+      if (type == 'weekly' || type == 'daily')
+        data[:when] = _when
+      end
+      api_post(:alert, data)
+    end
+
+
+    # params
+    #   email, String
+    #   alert_id, String
+    #
+    # delete user alert
+    def delete_alert(email, alert_id)
+      data = {:email => email, :alert_id => alert_id}
+      api_delete(:alert, data)
+    end
+
     protected
 
+    # Make Stats API Request
+    def stats(data)
+      api_get(:stats, data)
+    end
+
     # Perform API GET request
     def api_get(action, data)
       api_request(action, data, 'GET')
@@ -377,8 +617,15 @@ module Sailthru
 
 
       # NOTE: don't do the unserialize here
-      unserialized = JSON.parse(_result)
-      return unserialized ? unserialized : _result
+     if data[:format] == 'json'
+        begin
+           unserialized = JSON.parse(_result)
+          return unserialized ? unserialized : _result
+        rescue JSON::JSONError => e
+          return {'error' => e}
+        end
+     end
+     return _result
     end
 
 
@@ -397,7 +644,7 @@ module Sailthru
       end
       req = nil
       headers = {"User-Agent" => "Sailthru API Ruby Client #{VERSION}"}
-      
+
       _uri  = URI.parse(uri)
       if method == 'POST'
         req = Net::HTTP::Post.new(_uri.path, headers)
@@ -424,6 +671,6 @@ module Sailthru
       else
         raise SailthruClientException.new("No response received from stream: #{_uri.to_s}")
       end
-    end    
+    end
   end
 end

metadata

@@ -1,12 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: sailthru-client
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: 
   segments: 
   - 1
-  - 2
-  version: "1.02"
+  - 3
+  version: "1.03"
 platform: ruby
 authors: 
 - Prajwal Tuladhar
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-25 00:00:00 -05:00
+date: 2011-02-03 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency