createsend-sendowlfork 6.1.0.pre.hashie5

data/lib/createsend/createsend.rb

@@ -0,0 +1,291 @@
+require 'cgi'
+require 'uri'
+require 'httparty'
+require 'hashie'
+require 'json'
+
+module CreateSend
+
+  USER_AGENT_STRING = "createsend-ruby-#{VERSION}-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}-#{RUBY_PLATFORM}"
+
+  # Represents a CreateSend API error. Contains specific data about the error.
+  class CreateSendError < StandardError
+    attr_reader :data
+    def initialize(data)
+      @data = data
+      # @data should contain Code, Message and optionally ResultData
+      extra = @data.ResultData ? "\nExtra result data: #{@data.ResultData}" : ""
+      super "The CreateSend API responded with the following error"\
+        " - #{@data.Code}: #{@data.Message}#{extra}"
+    end
+  end
+
+  # Raised for HTTP response codes of 400...500
+  class ClientError < StandardError; end
+  # Raised for HTTP response codes of 500...600
+  class ServerError < StandardError; end
+  # Raised for HTTP response code of 400
+  class BadRequest < CreateSendError; end
+  # Raised for HTTP response code of 401
+  class Unauthorized < CreateSendError; end
+  # Raised for HTTP response code of 404
+  class NotFound < ClientError; end
+
+  # Raised for HTTP response code of 401, specifically when an OAuth token
+  # in invalid (Code: 120, Message: 'Invalid OAuth Token')
+  class InvalidOAuthToken < Unauthorized; end
+  # Raised for HTTP response code of 401, specifically when an OAuth token
+  # has expired (Code: 121, Message: 'Expired OAuth Token')
+  class ExpiredOAuthToken < Unauthorized; end
+  # Raised for HTTP response code of 401, specifically when an OAuth token
+  # has been revoked (Code: 122, Message: 'Revoked OAuth Token')
+  class RevokedOAuthToken < Unauthorized; end
+
+  # Provides high level CreateSend functionality/data you'll probably need.
+  class CreateSend
+    include HTTParty
+    default_timeout 120
+
+    attr_reader :auth_details
+
+    # Specify cert authority file for cert validation
+    ssl_ca_file File.expand_path(File.join(File.dirname(__FILE__), 'cacert.pem'))
+
+    # Set a custom user agent string to be used when instances of
+    # CreateSend::CreateSend make API calls.
+    #
+    # user_agent - The user agent string to use in the User-Agent header when
+    #              instances of this class make API calls. If set to nil, the
+    #              default value of CreateSend::USER_AGENT_STRING will be used.
+    def self.user_agent(user_agent)
+      headers({'User-Agent' => user_agent || USER_AGENT_STRING})
+    end
+
+    # Get the authorization URL for your application, given the application's
+    # client_id, redirect_uri, scope, and optional state data.
+    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 a provided OAuth code for an OAuth access token, 'expires in'
+    # value, and refresh token.
+    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 an OAuth access token, given an OAuth refresh token.
+    # Returns a new access token, 'expires in' value, and refresh token.
+    def self.refresh_access_token(refresh_token)
+      options = {
+        :body => "grant_type=refresh_token&refresh_token=#{CGI.escape(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
+
+    def initialize(*args)
+      if args.size > 0
+        auth args.first # Expect auth details as first argument
+      end
+    end
+
+    @@base_uri = "https://api.createsend.com/api/v3.3"
+    @@oauth_base_uri = "https://api.createsend.com/oauth"
+    @@oauth_token_uri = "#{@@oauth_base_uri}/token"
+    headers({
+      'User-Agent' => USER_AGENT_STRING,
+      'Content-Type' => 'application/json; charset=utf-8'
+    })
+    base_uri @@base_uri
+
+    # Authenticate using either OAuth or an API key.
+    def auth(auth_details)
+      @auth_details = auth_details
+    end
+
+    # Refresh the current OAuth token using the current refresh token.
+    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
+
+    # Gets your clients.
+    def clients
+      response = get('/clients.json')
+      response.map{|item| Hashie::Mash.new(item)}
+    end
+
+    # Get your billing details.
+    def billing_details
+      response = get('/billingdetails.json')
+      Hashie::Mash.new(response)
+    end
+
+    # Gets valid countries.
+    def countries
+      response = get('/countries.json')
+      response.parsed_response
+    end
+
+    # Gets the current date in your account's timezone.
+    def systemdate
+      response = get('/systemdate.json')
+      Hashie::Mash.new(response)
+    end
+
+    # Gets valid timezones.
+    def timezones
+      response = get('/timezones.json')
+      response.parsed_response
+    end
+
+    # Gets the administrators for the account.
+    def administrators
+      response = get('/admins.json')
+      response.map{|item| Hashie::Mash.new(item)}
+    end
+
+    # Gets the primary contact for the account.
+    def get_primary_contact
+      response = get('/primarycontact.json')
+      Hashie::Mash.new(response)
+    end
+
+    # Set the primary contect for the account.
+    def set_primary_contact(email)
+      options = { :query => { :email => email } }
+      response = put("/primarycontact.json", options)
+      Hashie::Mash.new(response)
+    end
+
+    # Get a URL which initiates a new external session for the user with the
+    # given email.
+    # Full details: http://www.campaignmonitor.com/api/account/#single_sign_on
+    #
+    # email         - The email address of the Campaign Monitor user for whom
+    #                 the login session should be created.
+    # chrome        - Which 'chrome' to display - Must be either "all",
+    #                 "tabs", or "none".
+    # url           - The URL to display once logged in. e.g. "/subscribers/"
+    # integrator_id - The integrator ID. You need to contact Campaign Monitor
+    #                 support to get an integrator ID.
+    # client_id     - The Client ID of the client which should be active once
+    #                 logged in to the Campaign Monitor account.
+    #
+    # Returns An object containing a single field SessionUrl which represents
+    # the URL to initiate the external Campaign Monitor session.
+    def external_session_url(email, chrome, url, integrator_id, client_id)
+      options = { :body => {
+        :Email => email,
+        :Chrome => chrome,
+        :Url => url,
+        :IntegratorID => integrator_id,
+        :ClientID => client_id }.to_json }
+      response = put("/externalsession.json", options)
+      Hashie::Mash.new(response)
+    end
+
+    def get(*args)
+      args = add_auth_details_to_options(args)
+      handle_response CreateSend.get(*args)
+    end
+    alias_method :cs_get, :get
+
+    def post(*args)
+      args = add_auth_details_to_options(args)
+      handle_response CreateSend.post(*args)
+    end
+    alias_method :cs_post, :post
+
+    def put(*args)
+      args = add_auth_details_to_options(args)
+      handle_response CreateSend.put(*args)
+    end
+    alias_method :cs_put, :put
+
+    def delete(*args)
+      args = add_auth_details_to_options(args)
+      handle_response CreateSend.delete(*args)
+    end
+    alias_method :cs_delete, :delete
+
+    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
+
+    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
+  end
+end

data/lib/createsend/journey.rb

@@ -0,0 +1,58 @@
+module CreateSend
+  # Represents a journey and provides associated functionality
+  class Journey < CreateSend
+    attr_reader :journey_id
+
+    def initialize(auth, journey_id)
+      @journey_id = journey_id
+      super
+    end
+
+    # Get a full summary of a journey
+    def summary
+      response = get "/journeys/#{@journey_id}.json"
+      Hashie::Mash.new(response)
+    end
+
+    # Gets a list of all recipients of a particular email within a journey
+    def email_recipients(email_id="", date="", page=1, page_size=1000, order_direction='asc')
+      paged_result_by_date("recipients", email_id, date, page, page_size, order_direction)
+    end
+
+    # Gets a paged list of subscribers who opened a given journey email
+    def email_opens(email_id="", date="", page=1, page_size=1000, order_direction='asc')
+      paged_result_by_date("opens", email_id, date, page, page_size, order_direction)
+    end
+
+    # Gets a paged list of subscribers who clicked a given journey email
+    def email_clicks(email_id="", date="", page=1, page_size=1000, order_direction='asc')
+      paged_result_by_date("clicks", email_id, date, page, page_size, order_direction)
+    end
+
+    # Gets a paged result representing all subscribers who unsubscribed from a journey email
+    def email_unsubscribes(email_id="", date="", page=1, page_size=1000, order_direction='asc')
+      paged_result_by_date("unsubscribes", email_id, date, page, page_size, order_direction)
+    end
+
+    # Gets a paged result of all bounces for a journey email
+    def email_bounces(email_id="", date="", page=1, page_size=1000, order_direction='asc')
+      paged_result_by_date("bounces", email_id, date, page, page_size, order_direction)
+    end
+
+    private
+
+    def paged_result_by_date(resource, email_id, date, page, page_size, order_direction)
+      options = { :query => {
+          :date => date,
+          :page => page,
+          :pagesize => page_size,
+          :orderdirection => order_direction } }
+      response = get_journey_email_action email_id, resource, options
+      Hashie::Mash.new(response)
+    end
+
+    def get_journey_email_action(email_id, action, options = {})
+      get "/journeys/email/#{email_id}/#{action}.json", options
+    end
+  end
+end

data/lib/createsend/list.rb

@@ -0,0 +1,258 @@
+module CreateSend
+  # Represents a subscriber list and associated functionality.
+  class List < CreateSend
+    attr_reader :list_id
+
+    def initialize(auth, list_id)
+      @list_id = list_id
+      super
+    end
+
+    # Creates a new list for a client.
+    # client_id - String representing the ID of the client for whom the list
+    #   will be created
+    # title - String representing the list title/name
+    # unsubscribe_page - String representing the url of the unsubscribe
+    #   confirmation page
+    # confirmed_opt_in - A Boolean representing whether this should be a
+    #   confirmed opt-in (double opt-in) list
+    # confirmation_success_page - String representing the url of the
+    #   confirmation success page
+    # unsubscribe_setting - A String which must be either "AllClientLists" or
+    #   "OnlyThisList". See the documentation for details:
+    #   http://www.campaignmonitor.com/api/lists/#creating_a_list
+    def self.create(auth, client_id, title, unsubscribe_page, confirmed_opt_in,
+      confirmation_success_page, unsubscribe_setting="AllClientLists")
+      options = { :body => {
+        :Title => title,
+        :UnsubscribePage => unsubscribe_page,
+        :ConfirmedOptIn => confirmed_opt_in,
+        :ConfirmationSuccessPage => confirmation_success_page,
+        :UnsubscribeSetting => unsubscribe_setting }.to_json }
+      cs = CreateSend.new auth
+      response = cs.post "/lists/#{client_id}.json", options
+      response.parsed_response
+    end
+
+    # Deletes this list.
+    def delete
+      super "/lists/#{list_id}.json", {}
+    end
+
+    # Creates a new custom field for this list.
+    # field_name - String representing the name to be given to the field
+    # data_type - String representing the data type of the field. Valid data
+    #   types are 'Text', 'Number', 'MultiSelectOne', 'MultiSelectMany',
+    #   'Date', 'Country', and 'USState'.
+    # options - Array of Strings representing the options for the field if it
+    #   is of type 'MultiSelectOne' or 'MultiSelectMany'.
+    # visible_in_preference_center - Boolean indicating whether or not the
+    #    field should be visible in the subscriber preference center
+    def create_custom_field(field_name, data_type, options=[],
+      visible_in_preference_center=true)
+      options = { :body => {
+        :FieldName => field_name,
+        :DataType => data_type,
+        :Options => options,
+        :VisibleInPreferenceCenter => visible_in_preference_center }.to_json }
+      response = post "customfields", options
+      response.parsed_response
+    end
+
+    # Updates a custom field belonging to this list.
+    # custom_field_key - String which represents the key for the custom field
+    # field_name - String representing the name to be given to the field
+    # visible_in_preference_center - Boolean indicating whether or not the
+    #    field should be visible in the subscriber preference center
+    def update_custom_field(custom_field_key, field_name,
+      visible_in_preference_center)
+      custom_field_key = CGI.escape(custom_field_key)
+      options = { :body => {
+        :FieldName => field_name,
+        :VisibleInPreferenceCenter => visible_in_preference_center }.to_json }
+      response = put "customfields/#{custom_field_key}", options
+      response.parsed_response
+    end
+
+    # Deletes a custom field associated with this list.
+    def delete_custom_field(custom_field_key)
+      custom_field_key = CGI.escape(custom_field_key)
+      cs_delete("/lists/#{list_id}/customfields/#{custom_field_key}.json", {})
+    end
+
+    # Updates the options of a multi-optioned custom field on this list.
+    def update_custom_field_options(custom_field_key, new_options,
+      keep_existing_options)
+      custom_field_key = CGI.escape(custom_field_key)
+      options = { :body => {
+        :Options => new_options,
+        :KeepExistingOptions => keep_existing_options }.to_json }
+      put "customfields/#{custom_field_key}/options", options
+    end
+
+    # Gets the details of this list.
+    def details
+      response = cs_get "/lists/#{list_id}.json"
+      Hashie::Mash.new(response)
+    end
+
+    # Gets the custom fields for this list.
+    def custom_fields
+      response = get "customfields"
+      response.map{|item| Hashie::Mash.new(item)}
+    end
+
+    # Gets the segments for this list.
+    def segments
+      response = get "segments"
+      response.map{|item| Hashie::Mash.new(item)}
+    end
+
+    # Gets the stats for this list.
+    def stats
+      response = get "stats"
+      Hashie::Mash.new(response)
+    end
+
+    # Gets the active subscribers for this list.
+    def active(date="", page=1, page_size=1000, order_field="email",
+      order_direction="asc", include_tracking_preference=false, include_sms_preference:false)
+      paged_result_by_date("active", date, page, page_size, order_field,
+        order_direction, include_tracking_preference, include_sms_preference)
+    end
+
+    # Gets the unconfirmed subscribers for this list.
+    def unconfirmed(date="", page=1, page_size=1000, order_field="email",
+      order_direction="asc", include_tracking_preference=false, include_sms_preference:false)
+      paged_result_by_date("unconfirmed", date, page, page_size, order_field,
+        order_direction, include_tracking_preference, include_sms_preference)
+    end
+
+    # Gets the bounced subscribers for this list.
+    def bounced(date="", page=1, page_size=1000, order_field="email",
+      order_direction="asc", include_tracking_preference=false, include_sms_preference:false)
+      paged_result_by_date("bounced", date, page, page_size, order_field,
+        order_direction, include_tracking_preference, include_sms_preference)
+    end
+
+    # Gets the unsubscribed subscribers for this list.
+    def unsubscribed(date="", page=1, page_size=1000, order_field="email",
+      order_direction="asc", include_tracking_preference=false, include_sms_preference:false)
+      paged_result_by_date("unsubscribed", date, page, page_size, order_field,
+        order_direction, include_tracking_preference, include_sms_preference)
+    end
+
+    # Gets the deleted subscribers for this list.
+    def deleted(date="", page=1, page_size=1000, order_field="email",
+      order_direction="asc", include_tracking_preference=false, include_sms_preference:false)
+      paged_result_by_date("deleted", date, page, page_size, order_field,
+        order_direction, include_tracking_preference, include_sms_preference)
+    end
+
+    # Updates this list.
+    # title - String representing the list title/name
+    # unsubscribe_page - String representing the url of the unsubscribe
+    #   confirmation page
+    # confirmed_opt_in - A Boolean representing whether this should be a
+    #   confirmed opt-in (double opt-in) list
+    # confirmation_success_page - String representing the url of the
+    #   confirmation success page
+    # unsubscribe_setting - A String which must be either "AllClientLists" or
+    #   "OnlyThisList". See the documentation for details:
+    #   http://www.campaignmonitor.com/api/lists/#updating_a_list
+    # add_unsubscribes_to_supp_list - When unsubscribe_setting is
+    #   "AllClientLists", a Boolean which represents whether unsubscribes from
+    #   this list should be added to the suppression list
+    # scrub_active_with_supp_list - When unsubscribe_setting is
+    #   "AllClientLists", a Boolean which represents whether active sunscribers
+    #   should be scrubbed against the suppression list
+    def update(title, unsubscribe_page, confirmed_opt_in,
+      confirmation_success_page, unsubscribe_setting="AllClientLists",
+      add_unsubscribes_to_supp_list=false, scrub_active_with_supp_list=false)
+      options = { :body => {
+        :Title => title,
+        :UnsubscribePage => unsubscribe_page,
+        :ConfirmedOptIn => confirmed_opt_in,
+        :ConfirmationSuccessPage => confirmation_success_page,
+        :UnsubscribeSetting => unsubscribe_setting,
+        :AddUnsubscribesToSuppList => add_unsubscribes_to_supp_list,
+        :ScrubActiveWithSuppList => scrub_active_with_supp_list }.to_json }
+      cs_put "/lists/#{list_id}.json", options
+    end
+
+    # Gets the webhooks for this list.
+    def webhooks
+      response = get "webhooks"
+      response.map{|item| Hashie::Mash.new(item)}
+    end
+
+    # Creates a new webhook for the specified events (an array of strings).
+    # Valid events are "Subscribe", "Deactivate", and "Update".
+    # Valid payload formats are "json", and "xml".
+    def create_webhook(events, url, payload_format)
+      options = { :body => {
+        :Events => events,
+        :Url => url,
+        :PayloadFormat => payload_format }.to_json }
+      response = post "webhooks", options
+      response.parsed_response
+    end
+
+    # Tests that a post can be made to the endpoint specified for the webhook
+    # identified by webhook_id.
+    def test_webhook(webhook_id)
+      get "webhooks/#{webhook_id}/test"
+      true # An exception will be raised if any error occurs
+    end
+
+    # Deletes a webhook associated with this list.
+    def delete_webhook(webhook_id)
+      cs_delete("/lists/#{list_id}/webhooks/#{webhook_id}.json", {})
+    end
+
+    # Activates a webhook associated with this list.
+    def activate_webhook(webhook_id)
+      options = { :body => '' }
+      put "webhooks/#{webhook_id}/activate", options
+    end
+
+    # De-activates a webhook associated with this list.
+    def deactivate_webhook(webhook_id)
+      options = { :body => '' }
+      put "webhooks/#{webhook_id}/deactivate", options
+    end
+
+    private
+    
+    def paged_result_by_date(resource, date, page, page_size, order_field,
+      order_direction, include_tracking_preference, include_sms_preference)
+      options = { :query => {
+        :date => date,
+        :page => page,
+        :pagesize => page_size,
+        :orderfield => order_field,
+        :orderdirection => order_direction,
+        :includetrackingpreference => include_tracking_preference,
+        :includesmspreference => include_sms_preference} }
+      response = get resource, options
+      Hashie::Mash.new(response)
+    end
+
+    def get(action, options = {})
+      super uri_for(action), options
+    end
+
+    def post(action, options = {})
+      super uri_for(action), options
+    end
+
+    def put(action, options = {})
+      super uri_for(action), options
+    end
+
+    def uri_for(action)
+      "/lists/#{list_id}/#{action}.json"
+    end
+
+  end
+end

data/lib/createsend/person.rb

@@ -0,0 +1,59 @@
+module CreateSend
+  # Represents a person and associated functionality.
+  class Person < CreateSend
+    attr_reader :client_id
+    attr_reader :email_address
+
+    def initialize(auth, client_id, email_address)
+      @client_id = client_id
+      @email_address = email_address
+      super
+    end
+
+    # Gets a person by client ID and email address.
+    def self.get(auth, client_id, email_address)
+      options = { :query => { :email => email_address } }
+      cs = CreateSend.new auth
+      response = cs.get "/clients/#{client_id}/people.json", options
+      Hashie::Mash.new(response)
+    end
+
+    # Adds a person to the client. Password is optional. If ommitted, an
+    # email invitation will be sent to the person
+    def self.add(auth, client_id, email_address, name, access_level, password)
+      options = { :body => {
+        :EmailAddress => email_address,
+        :Name => name,
+        :AccessLevel => access_level,
+        :Password => password }.to_json }
+      cs = CreateSend.new auth
+      response = cs.post "/clients/#{client_id}/people.json", options
+      Hashie::Mash.new(response)
+    end
+
+    # Updates the person details. password is optional and will only be
+    # updated if supplied
+    def update(new_email_address, name, access_level, password)
+      options = {
+        :query => { :email => @email_address },
+        :body => {
+          :EmailAddress => new_email_address,
+          :Name => name,
+          :AccessLevel => access_level,
+          :Password => password }.to_json }
+      put uri_for(client_id), options
+      # Update @email_address, so this object can continue to be used reliably
+      @email_address = new_email_address
+    end
+
+    # deletes this person from the client
+    def delete
+      options = { :query => { :email => @email_address } }
+      super uri_for(client_id), options
+    end
+
+    def uri_for(client_id)
+      "/clients/#{client_id}/people.json"
+    end
+  end
+end