pushradar 0.9.0

data/lib/PushRadar/APIClient.rb

@@ -0,0 +1,50 @@
+require 'PushRadar/version'
+require 'PushRadar/Targeting'
+require 'net/http'
+require 'json'
+
+module PushRadar
+
+  # A client that interacts with PushRadar's API
+  class APIClient
+
+    # Creates a new instance of the PushRadar API client with the specified API secret
+    def initialize(api_secret)
+
+      # Set the API secret
+      api_secret.strip!
+      @api_secret = api_secret
+
+      # Set the API endpoint
+      @api_endpoint = 'https://api.pushradar.com/v1'
+
+    end
+
+    # Performs a POST request to the API destination specified
+    def post(destination, data)
+
+      # Add in the fields that should be sent with each request
+      data['api_secret'] = @api_secret
+      data['client_platform'] = 'ruby'
+      data['request_sent_at'] = Time.now.to_i
+
+      # Make sure the destination does not contain the base URL or forward slash characters
+      destination = destination.gsub('/', '')
+      destination.sub! @api_endpoint, ''
+
+      # Construct the actual URL to POST the data to
+      url = @api_endpoint + '/' + destination
+
+      # Send a POST request to the server
+      uri = URI(url)
+      req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
+      req.body = data.to_json
+      Net::HTTP.start(uri.hostname, uri.port) do |http|
+        http.request(req)
+      end
+
+    end
+
+  end
+
+end

data/lib/PushRadar/Targeting.rb

@@ -0,0 +1,201 @@
+require 'PushRadar/version'
+require 'PushRadar/Utils'
+require 'ipaddr'
+
+module PushRadar
+
+  # Specifies the target audience of a PushRadar notification
+  class Targeting
+
+    # ------------------------------
+    # Initialization & configuration
+    # ------------------------------
+
+    # Creates a new notification targeting object
+    def initialize
+
+      # Initialize variables
+      @target_user_ids = []
+      @target_actions = []
+      @target_not_actions = []
+      @target_browsers = []
+      @target_continents = []
+      @target_countries = []
+      @target_ips = []
+
+    end
+
+    # ------------------------------
+    # Browser targeting
+    # ------------------------------
+
+    # Adds a browser to the list of target browsers
+    def target_browser(browser)
+
+      # Trim the browser and convert it to lowercase
+      browser.strip!
+      browser.downcase
+
+      # Validate the browser for being one of the supported types
+      unless %w(chrome ie edge safari opera firefox).include? browser
+        raise "The browser must be one of the following: 'chrome', 'ie', 'edge', 'safari', 'opera', 'firefox'."
+      end
+
+      # Add the browser to the list of target browser
+      unless @target_browsers.include? browser
+        @target_browsers.push browser
+      end
+
+    end
+
+    # ------------------------------
+    # Country targeting
+    # ------------------------------
+
+    # Adds a country to the list of target countries
+    def target_country(country_code)
+
+      # Trim the country code and convert it to uppercase
+      country_code.strip!
+      country_code.upcase
+
+      # Ensure that the country code is not empty
+      if country_code == ''
+        raise 'The country code provided cannot be empty.'
+      end
+
+      # Validate the country code
+      unless Utils.get_countries.keys.include? country_code.to_sym
+        raise 'The country code provided must be a valid two-letter (ISO 3166-1 alpha-2) code.'
+      end
+
+      # Add the country to the list
+      unless @target_countries.include? country_code
+        @target_countries.push country_code
+      end
+
+    end
+
+    # ------------------------------
+    # Continent targeting
+    # ------------------------------
+
+    # Targets a continent by its continent code
+    def target_continent(continent_code)
+
+      # Target the countries located in this continent
+      Utils.get_countries_from_continent(continent_code).each {|country|
+        target_country country
+      }
+
+      # Add the continent code to the list
+      unless @target_continents.include? continent_code
+        @target_continents.push continent_code
+      end
+
+    end
+
+    # ------------------------------
+    # IP address targeting
+    # ------------------------------
+
+    # Targets the notification to clients with the given IP address
+    def target_ip(ip_address)
+
+      # Trim the IP address
+      ip_address.strip!
+
+      # Make sure that the IP address is not empty
+      if ip_address == ''
+        raise 'The IP address provided cannot be empty.'
+      end
+
+      # Check for wildcard IPs
+      if ip_address.include? '*'
+        raise 'Wildcard IP address targeting is not supported.'
+      end
+
+      # Validate the IP address
+      unless Utils.is_valid_ip ip_address
+        raise 'The IP address provided must be a valid IPv4 or IPv6 address.'
+      end
+
+      # Add the IP address to the list
+      unless @target_ips.include? ip_address
+        @target_ips.push ip_address
+      end
+
+    end
+
+    # ------------------------------
+    # Action targeting
+    # ------------------------------
+
+    # Targets the notification to clients who have taken the given action
+    def target_action(action_identifier)
+
+      # Trim the action identifier
+      action_identifier.strip!
+
+      # Make sure the action identifier is not empty
+      if action_identifier == ''
+        raise 'The action identifier cannot be empty'
+      end
+
+      # Make sure that the action is not in the target "not" actions list
+      if @target_not_actions.include? action_identifier
+        raise "Action '" + action_identifier + "' is already in the 'not' actions list."
+      end
+
+      # Add the action to the list
+      unless @target_actions.include? action_identifier
+        @target_actions.push action_identifier
+      end
+
+    end
+
+    # Targets the notification to clients who have not taken the given action
+    def target_not_action(action_identifier)
+
+      # Trim the action identifier
+      action_identifier.strip!
+
+      # Make sure the action identifier is not empty
+      if action_identifier == ''
+        raise 'The action identifier cannot be empty'
+      end
+
+      # Make sure that the action is not in the target actions list
+      if @target_actions.include? action_identifier
+        raise "Action '" + action_identifier + "' is already in the actions list."
+      end
+
+      # Add the action to the list
+      unless @target_not_actions.include? action_identifier
+        @target_not_actions.push action_identifier
+      end
+
+    end
+
+    # ------------------------------
+    # User targeting
+    # ------------------------------
+
+    # Targets the notification to a specific user (identifier by their user ID)
+    def target_user(user_id)
+
+      # Make sure that the user ID is not empty
+      if user_id == nil
+        raise 'The user ID cannot be nil.'
+      end
+
+      # Add the user ID to the list
+      unless @target_user_ids.include? user_id
+        @target_user_ids.push user_id
+      end
+
+    end
+
+  end
+
+end

data/lib/PushRadar/Utils.rb

@@ -0,0 +1,570 @@
+require 'PushRadar/version'
+require 'resolv'
+
+module PushRadar
+
+  # Contains helpful methods that are used throughout the library
+  class Utils
+
+    # ------------------------------
+    # Collection utilities
+    # ------------------------------
+
+    # Searches the given dictionary for values matching the value provided, and returns the keys of those elements
+    def self.keys_where_value(dictionary, value)
+
+      # Select the keys
+      keys = []
+      dictionary.each {|x|
+        if dictionary[x] == value
+          keys.push value
+        end
+      }
+
+      # Return the keys
+      keys
+
+    end
+
+    # ------------------------------
+    # Location utilities
+    # ------------------------------
+
+    # Gets a hash that associates ISO 3166-1 alpha-2 country codes with country names
+    def self.get_countries
+
+      {AD: 'Andorra',
+       AE: 'United Arab Emirates',
+       AF: 'Afghanistan',
+       AG: 'Antigua and Barbuda',
+       AI: 'Anguilla',
+       AL: 'Albania',
+       AM: 'Armenia',
+       AO: 'Angola',
+       AQ: 'Antarctica',
+       AR: 'Argentina',
+       AS: 'American Samoa',
+       AT: 'Austria',
+       AU: 'Australia',
+       AW: 'Aruba',
+       AX: 'Åland Islands',
+       AZ: 'Azerbaijan',
+       BA: 'Bosnia and Herzegovina',
+       BB: 'Barbados',
+       BD: 'Bangladesh',
+       BE: 'Belgium',
+       BF: 'Burkina Faso',
+       BG: 'Bulgaria',
+       BH: 'Bahrain',
+       BI: 'Burundi',
+       BJ: 'Benin',
+       BL: 'Saint Barthélemy',
+       BM: 'Bermuda',
+       BN: 'Brunei Darussalam',
+       BO: 'Bolivia, Plurinational State of',
+       BQ: 'Bonaire, Sint Eustatius and Saba',
+       BR: 'Brazil',
+       BS: 'Bahamas',
+       BT: 'Bhutan',
+       BV: 'Bouvet Island',
+       BW: 'Botswana',
+       BY: 'Belarus',
+       BZ: 'Belize',
+       CA: 'Canada',
+       CC: 'Cocos (Keeling) Islands',
+       CD: 'Congo, the Democratic Republic of the',
+       CF: 'Central African Republic',
+       CG: 'Congo',
+       CH: 'Switzerland',
+       CI: 'Côte d\'Ivoire',
+       CK: 'Cook Islands',
+       CL: 'Chile',
+       CM: 'Cameroon',
+       CN: 'China',
+       CO: 'Colombia',
+       CR: 'Costa Rica',
+       CU: 'Cuba',
+       CV: 'Cabo Verde',
+       CW: 'Curaçao',
+       CX: 'Christmas Island',
+       CY: 'Cyprus',
+       CZ: 'Czechia',
+       DE: 'Germany',
+       DJ: 'Djibouti',
+       DK: 'Denmark',
+       DM: 'Dominica',
+       DO: 'Dominican Republic',
+       DZ: 'Algeria',
+       EC: 'Ecuador',
+       EE: 'Estonia',
+       EG: 'Egypt',
+       EH: 'Western Sahara',
+       ER: 'Eritrea',
+       ES: 'Spain',
+       ET: 'Ethiopia',
+       FI: 'Finland',
+       FJ: 'Fiji',
+       FK: 'Falkland Islands (Malvinas)',
+       FM: 'Micronesia, Federated States of',
+       FO: 'Faroe Islands',
+       FR: 'France',
+       GA: 'Gabon',
+       GB: 'United Kingdom of Great Britain and Northern Ireland',
+       GD: 'Grenada',
+       GE: 'Georgia',
+       GF: 'French Guiana',
+       GG: 'Guernsey',
+       GH: 'Ghana',
+       GI: 'Gibraltar',
+       GL: 'Greenland',
+       GM: 'Gambia',
+       GN: 'Guinea',
+       GP: 'Guadeloupe',
+       GQ: 'Equatorial Guinea',
+       GR: 'Greece',
+       GS: 'South Georgia and the South Sandwich Islands',
+       GT: 'Guatemala',
+       GU: 'Guam',
+       GW: 'Guinea-Bissau',
+       GY: 'Guyana',
+       HK: 'Hong Kong',
+       HM: 'Heard Island and McDonald Islands',
+       HN: 'Honduras',
+       HR: 'Croatia',
+       HT: 'Haiti',
+       HU: 'Hungary',
+       ID: 'Indonesia',
+       IE: 'Ireland',
+       IL: 'Israel',
+       IM: 'Isle of Man',
+       IN: 'India',
+       IO: 'British Indian Ocean Territory',
+       IQ: 'Iraq',
+       IR: 'Iran, Islamic Republic of',
+       IS: 'Iceland',
+       IT: 'Italy',
+       JE: 'Jersey',
+       JM: 'Jamaica',
+       JO: 'Jordan',
+       JP: 'Japan',
+       KE: 'Kenya',
+       KG: 'Kyrgyzstan',
+       KH: 'Cambodia',
+       KI: 'Kiribati',
+       KM: 'Comoros',
+       KN: 'Saint Kitts and Nevis',
+       KP: 'Korea, Democratic People\'s Republic of',
+       KR: 'Korea, Republic of',
+       KW: 'Kuwait',
+       KY: 'Cayman Islands',
+       KZ: 'Kazakhstan',
+       LA: 'Lao People\'s Democratic Republic',
+       LB: 'Lebanon',
+       LC: 'Saint Lucia',
+       LI: 'Liechtenstein',
+       LK: 'Sri Lanka',
+       LR: 'Liberia',
+       LS: 'Lesotho',
+       LT: 'Lithuania',
+       LU: 'Luxembourg',
+       LV: 'Latvia',
+       LY: 'Libya',
+       MA: 'Morocco',
+       MC: 'Monaco',
+       MD: 'Moldova, Republic of',
+       ME: 'Montenegro',
+       MF: 'Saint Martin (French part)',
+       MG: 'Madagascar',
+       MH: 'Marshall Islands',
+       MK: 'Macedonia, the former Yugoslav Republic of',
+       ML: 'Mali',
+       MM: 'Myanmar',
+       MN: 'Mongolia',
+       MO: 'Macao',
+       MP: 'Northern Mariana Islands',
+       MQ: 'Martinique',
+       MR: 'Mauritania',
+       MS: 'Montserrat',
+       MT: 'Malta',
+       MU: 'Mauritius',
+       MV: 'Maldives',
+       MW: 'Malawi',
+       MX: 'Mexico',
+       MY: 'Malaysia',
+       MZ: 'Mozambique',
+       NA: 'Namibia',
+       NC: 'New Caledonia',
+       NE: 'Niger',
+       NF: 'Norfolk Island',
+       NG: 'Nigeria',
+       NI: 'Nicaragua',
+       NL: 'Netherlands',
+       NO: 'Norway',
+       NP: 'Nepal',
+       NR: 'Nauru',
+       NU: 'Niue',
+       NZ: 'New Zealand',
+       OM: 'Oman',
+       PA: 'Panama',
+       PE: 'Peru',
+       PF: 'French Polynesia',
+       PG: 'Papua New Guinea',
+       PH: 'Philippines',
+       PK: 'Pakistan',
+       PL: 'Poland',
+       PM: 'Saint Pierre and Miquelon',
+       PN: 'Pitcairn',
+       PR: 'Puerto Rico',
+       PS: 'Palestine, State of',
+       PT: 'Portugal',
+       PW: 'Palau',
+       PY: 'Paraguay',
+       QA: 'Qatar',
+       RE: 'Réunion',
+       RO: 'Romania',
+       RS: 'Serbia',
+       RU: 'Russian Federation',
+       RW: 'Rwanda',
+       SA: 'Saudi Arabia',
+       SB: 'Solomon Islands',
+       SC: 'Seychelles',
+       SD: 'Sudan',
+       SE: 'Sweden',
+       SG: 'Singapore',
+       SH: 'Saint Helena, Ascension and Tristan da Cunha',
+       SI: 'Slovenia',
+       SJ: 'Svalbard and Jan Mayen',
+       SK: 'Slovakia',
+       SL: 'Sierra Leone',
+       SM: 'San Marino',
+       SN: 'Senegal',
+       SO: 'Somalia',
+       SR: 'Suriname',
+       SS: 'South Sudan',
+       ST: 'Sao Tome and Principe',
+       SV: 'El Salvador',
+       SX: 'Sint Maarten (Dutch part)',
+       SY: 'Syrian Arab Republic',
+       SZ: 'Swaziland',
+       TC: 'Turks and Caicos Islands',
+       TD: 'Chad',
+       TF: 'French Southern Territories',
+       TG: 'Togo',
+       TH: 'Thailand',
+       TJ: 'Tajikistan',
+       TK: 'Tokelau',
+       TL: 'Timor-Leste',
+       TM: 'Turkmenistan',
+       TN: 'Tunisia',
+       TO: 'Tonga',
+       TR: 'Turkey',
+       TT: 'Trinidad and Tobago',
+       TV: 'Tuvalu',
+       TW: 'Taiwan, Province of China',
+       TZ: 'Tanzania, United Republic of',
+       UA: 'Ukraine',
+       UG: 'Uganda',
+       UM: 'United States Minor Outlying Islands',
+       US: 'United States of America',
+       UY: 'Uruguay',
+       UZ: 'Uzbekistan',
+       VA: 'Holy See',
+       VC: 'Saint Vincent and the Grenadines',
+       VE: 'Venezuela, Bolivarian Republic of',
+       VG: 'Virgin Islands, British',
+       VI: 'Virgin Islands, U.S.',
+       VN: 'Viet Nam',
+       VU: 'Vanuatu',
+       WF: 'Wallis and Futuna',
+       WS: 'Samoa',
+       YE: 'Yemen',
+       YT: 'Mayotte',
+       ZA: 'South Africa',
+       ZM: 'Zambia',
+       ZW: 'Zimbabwe'}
+
+    end
+
+    # Gets a hash that associates ISO 3166-1 alpha-2 country codes with two-letter continent codes
+    def self.get_country_continent_hash
+
+      # Return the hash
+      {AD: 'EU',
+       AE: 'AS',
+       AF: 'AS',
+       AG: 'NA',
+       AI: 'NA',
+       AL: 'EU',
+       AM: 'AS',
+       AO: 'AF',
+       AQ: 'AN',
+       AR: 'SA',
+       AS: 'OC',
+       AT: 'EU',
+       AU: 'OC',
+       AW: 'NA',
+       AX: 'EU',
+       AZ: 'AS',
+       BA: 'EU',
+       BB: 'NA',
+       BD: 'AS',
+       BE: 'EU',
+       BF: 'AF',
+       BG: 'EU',
+       BH: 'AS',
+       BI: 'AF',
+       BJ: 'AF',
+       BL: 'NA',
+       BM: 'NA',
+       BN: 'AS',
+       BO: 'SA',
+       BR: 'SA',
+       BS: 'NA',
+       BT: 'AS',
+       BV: 'AN',
+       BW: 'AF',
+       BY: 'EU',
+       BZ: 'NA',
+       CA: 'NA',
+       CC: 'AS',
+       CD: 'AF',
+       CF: 'AF',
+       CG: 'AF',
+       CH: 'EU',
+       CI: 'AF',
+       CK: 'OC',
+       CL: 'SA',
+       CM: 'AF',
+       CN: 'AS',
+       CO: 'SA',
+       CR: 'NA',
+       CU: 'NA',
+       CV: 'AF',
+       CX: 'AS',
+       CY: 'AS',
+       CZ: 'EU',
+       DE: 'EU',
+       DJ: 'AF',
+       DK: 'EU',
+       DM: 'NA',
+       DO: 'NA',
+       DZ: 'AF',
+       EC: 'SA',
+       EE: 'EU',
+       EG: 'AF',
+       EH: 'AF',
+       ER: 'AF',
+       ES: 'EU',
+       ET: 'AF',
+       FI: 'EU',
+       FJ: 'OC',
+       FK: 'SA',
+       FM: 'OC',
+       FO: 'EU',
+       FR: 'EU',
+       GA: 'AF',
+       GB: 'EU',
+       GD: 'NA',
+       GE: 'AS',
+       GF: 'SA',
+       GG: 'EU',
+       GH: 'AF',
+       GI: 'EU',
+       GL: 'NA',
+       GM: 'AF',
+       GN: 'AF',
+       GP: 'NA',
+       GQ: 'AF',
+       GR: 'EU',
+       GS: 'AN',
+       GT: 'NA',
+       GU: 'OC',
+       GW: 'AF',
+       GY: 'SA',
+       HK: 'AS',
+       HM: 'AN',
+       HN: 'NA',
+       HR: 'EU',
+       HT: 'NA',
+       HU: 'EU',
+       ID: 'AS',
+       IE: 'EU',
+       IL: 'AS',
+       IM: 'EU',
+       IN: 'AS',
+       IO: 'AS',
+       IQ: 'AS',
+       IR: 'AS',
+       IS: 'EU',
+       IT: 'EU',
+       JE: 'EU',
+       JM: 'NA',
+       JO: 'AS',
+       JP: 'AS',
+       KE: 'AF',
+       KG: 'AS',
+       KH: 'AS',
+       KI: 'OC',
+       KM: 'AF',
+       KN: 'NA',
+       KP: 'AS',
+       KR: 'AS',
+       KW: 'AS',
+       KY: 'NA',
+       KZ: 'AS',
+       LA: 'AS',
+       LB: 'AS',
+       LC: 'NA',
+       LI: 'EU',
+       LK: 'AS',
+       LR: 'AF',
+       LS: 'AF',
+       LT: 'EU',
+       LU: 'EU',
+       LV: 'EU',
+       LY: 'AF',
+       MA: 'AF',
+       MC: 'EU',
+       MD: 'EU',
+       ME: 'EU',
+       MF: 'NA',
+       MG: 'AF',
+       MH: 'OC',
+       MK: 'EU',
+       ML: 'AF',
+       MM: 'AS',
+       MN: 'AS',
+       MO: 'AS',
+       MP: 'OC',
+       MQ: 'NA',
+       MR: 'AF',
+       MS: 'NA',
+       MT: 'EU',
+       MU: 'AF',
+       MV: 'AS',
+       MW: 'AF',
+       MX: 'NA',
+       MY: 'AS',
+       MZ: 'AF',
+       NA: 'AF',
+       NC: 'OC',
+       NE: 'AF',
+       NF: 'OC',
+       NG: 'AF',
+       NI: 'NA',
+       NL: 'EU',
+       NO: 'EU',
+       NP: 'AS',
+       NR: 'OC',
+       NU: 'OC',
+       NZ: 'OC',
+       OM: 'AS',
+       PA: 'NA',
+       PE: 'SA',
+       PF: 'OC',
+       PG: 'OC',
+       PH: 'AS',
+       PK: 'AS',
+       PL: 'EU',
+       PM: 'NA',
+       PN: 'OC',
+       PR: 'NA',
+       PS: 'AS',
+       PT: 'EU',
+       PW: 'OC',
+       PY: 'SA',
+       QA: 'AS',
+       RE: 'AF',
+       RO: 'EU',
+       RS: 'EU',
+       RU: 'EU',
+       RW: 'AF',
+       SA: 'AS',
+       SB: 'OC',
+       SC: 'AF',
+       SD: 'AF',
+       SE: 'EU',
+       SG: 'AS',
+       SH: 'AF',
+       SI: 'EU',
+       SJ: 'EU',
+       SK: 'EU',
+       SL: 'AF',
+       SM: 'EU',
+       SN: 'AF',
+       SO: 'AF',
+       SR: 'SA',
+       ST: 'AF',
+       SV: 'NA',
+       SY: 'AS',
+       SZ: 'AF',
+       TC: 'NA',
+       TD: 'AF',
+       TF: 'AN',
+       TG: 'AF',
+       TH: 'AS',
+       TJ: 'AS',
+       TK: 'OC',
+       TL: 'AS',
+       TM: 'AS',
+       TN: 'AF',
+       TO: 'OC',
+       TR: 'EU',
+       TT: 'NA',
+       TV: 'OC',
+       TW: 'AS',
+       TZ: 'AF',
+       UA: 'EU',
+       UG: 'AF',
+       UM: 'OC',
+       US: 'NA',
+       UY: 'SA',
+       UZ: 'AS',
+       VA: 'EU',
+       VC: 'NA',
+       VE: 'SA',
+       VG: 'NA',
+       VI: 'NA',
+       VN: 'AS',
+       VU: 'OC',
+       WF: 'OC',
+       WS: 'OC',
+       YE: 'AS',
+       YT: 'AF',
+       ZA: 'AF',
+       ZM: 'AF',
+       ZW: 'AF'}
+
+    end
+
+    # Gets a list of ISO 3166-1 alpha-2 country codes, corresponding to countries located within the given continent
+    def self.get_countries_from_continent(continent_code)
+
+      # Convert the continent code to uppercase
+      continent_code.strip!
+      continent_code.upcase
+
+      # Get the country codes where the value equals the continent code
+      keys_where_value(get_country_continent_hash, continent_code)
+
+    end
+
+    # ------------------------------
+    # IP address utilities
+    # ------------------------------
+
+    # Checks whether the given IP address is valid
+    def self.is_valid_ip(addr)
+      case addr
+        when Resolv::IPv4::Regex
+          return true
+        when Resolv::IPv6::Regex
+          return true
+        else
+          return false
+      end
+    end
+
+  end
+
+end