customerio 2.1.0 → 4.0.0

data/lib/customerio/client.rb

@@ -1,29 +1,22 @@
-require 'net/http'
-require 'multi_json'
+require "addressable/uri"
 
 module Customerio
-  DEFAULT_BASE_URI = 'https://track.customer.io'
-  DEFAULT_TIMEOUT  = 10
-
   class Client
+    PUSH_OPENED = 'opened'
+    PUSH_CONVERTED = 'converted'
+    PUSH_DELIVERED = 'delivered'
+
+    VALID_PUSH_EVENTS = [PUSH_OPENED, PUSH_CONVERTED, PUSH_DELIVERED]
+
     class MissingIdAttributeError < RuntimeError; end
     class ParamError < RuntimeError; end
-    class InvalidRequest < RuntimeError; end
-    class InvalidResponse < RuntimeError
-      attr_reader :response
 
-      def initialize(message, response)
-        @message = message
-        @response = response
-      end
-    end
+    def initialize(site_id, api_key, options = {})
+      options[:region] = Customerio::Regions::US if options[:region].nil?
+      raise "region must be an instance of Customerio::Regions::Region" unless options[:region].is_a?(Customerio::Regions::Region)
 
-    def initialize(site_id, secret_key, options = {})
-      @username = site_id
-      @password = secret_key
-      @json = options.has_key?(:json) ? options[:json] : true
-      @base_uri = options[:base_uri] || DEFAULT_BASE_URI
-      @timeout = options[:timeout] || DEFAULT_TIMEOUT
+      options[:url] = options[:region].track_url if options[:url].nil? || options[:url].empty?
+      @client = Customerio::BaseClient.new({ site_id: site_id, api_key: api_key }, options)
     end
 
     def identify(attributes)
@@ -31,41 +24,38 @@ module Customerio
     end
 
     def delete(customer_id)
-      verify_response(request(:delete, customer_path(customer_id)))
+      raise ParamError.new("customer_id must be a non-empty string") if is_empty?(customer_id)
+      @client.request_and_verify_response(:delete, customer_path(customer_id))
     end
 
     def suppress(customer_id)
-      verify_response(request(:post, suppress_path(customer_id)))
+      raise ParamError.new("customer_id must be a non-empty string") if is_empty?(customer_id)
+      @client.request_and_verify_response(:post, suppress_path(customer_id))
     end
 
     def unsuppress(customer_id)
-      verify_response(request(:post, unsuppress_path(customer_id)))
+      raise ParamError.new("customer_id must be a non-empty string") if is_empty?(customer_id)
+      @client.request_and_verify_response(:post, unsuppress_path(customer_id))
     end
 
-    def track(*args)
-      attributes = extract_attributes(args)
-
-      if args.length == 1
-        # Only passed in an event name, create an anonymous event
-        event_name = args.first
-        create_anonymous_event(event_name, attributes)
-      else
-        # Passed in a customer id and an event name.
-        # Track the event for the given customer
-        customer_id, event_name = args
+    def track(customer_id, event_name, attributes = {})
+      raise ParamError.new("customer_id must be a non-empty string") if is_empty?(customer_id)
+      raise ParamError.new("event_name must be a non-empty string") if is_empty?(event_name)
 
-        create_customer_event(customer_id, event_name, attributes)
-      end
+      create_customer_event(customer_id, event_name, attributes)
     end
 
-    def anonymous_track(event_name, attributes = {})
-      create_anonymous_event(event_name, attributes)
+    def track_anonymous(anonymous_id, event_name, attributes = {})
+      raise ParamError.new("anonymous_id must be a non-empty string") if is_empty?(anonymous_id)
+      raise ParamError.new("event_name must be a non-empty string") if is_empty?(event_name)
+
+      create_anonymous_event(anonymous_id, event_name, attributes)
     end
 
     def add_device(customer_id, device_id, platform, data={})
-      raise ParamError.new("customer_id must be a non-empty string") unless customer_id != "" and !customer_id.nil?
-      raise ParamError.new("device_id must be a non-empty string") unless device_id != "" and !device_id.nil?
-      raise ParamError.new("platform must be a non-empty string") unless platform != "" and !platform.nil?
+      raise ParamError.new("customer_id must be a non-empty string") if is_empty?(customer_id)
+      raise ParamError.new("device_id must be a non-empty string") if is_empty?(device_id)
+      raise ParamError.new("platform must be a non-empty string") if is_empty?(platform)
 
       if data.nil?
         data = {}
@@ -73,125 +63,104 @@ module Customerio
 
       raise ParamError.new("data parameter must be a hash") unless data.is_a?(Hash)
 
-      verify_response(request(:put, device_path(customer_id), {
+      @client.request_and_verify_response(:put, device_path(customer_id), {
         :device => data.update({
           :id => device_id,
           :platform => platform,
         })
-      }))
+      })
     end
 
     def delete_device(customer_id, device_id)
-      raise ParamError.new("customer_id must be a non-empty string") unless customer_id != "" and !customer_id.nil?
-      raise ParamError.new("device_id must be a non-empty string") unless device_id != "" and !device_id.nil?
-      
-      verify_response(request(:delete, device_id_path(customer_id, device_id)))
-    end
-
-    private
+      raise ParamError.new("customer_id must be a non-empty string") if is_empty?(customer_id)
+      raise ParamError.new("device_id must be a non-empty string") if is_empty?(device_id)
 
-    def device_path(customer_id)
-      "/api/v1/customers/#{customer_id}/devices"
-    end
-
-    def device_id_path(customer_id, device_id)
-      "/api/v1/customers/#{customer_id}/devices/#{device_id}"
+      @client.request_and_verify_response(:delete, device_id_path(customer_id, device_id))
     end
 
-    def create_or_update(attributes = {})
-      attributes = Hash[attributes.map { |(k,v)| [ k.to_sym, v ] }]
+    def track_push_notification_event(event_name, attributes = {})
+        keys = [:delivery_id, :device_id, :timestamp]
+        attributes = Hash[attributes.map { |(k,v)| [ k.to_sym, v ] }].
+            select { |k, v| keys.include?(k) }
 
-      raise MissingIdAttributeError.new("Must provide a customer id") unless attributes[:id]
+        raise ParamError.new('event_name must be one of opened, converted, or delivered') unless VALID_PUSH_EVENTS.include?(event_name)
+        raise ParamError.new('delivery_id must be a non-empty string') unless attributes[:delivery_id] != "" and !attributes[:delivery_id].nil?
+        raise ParamError.new('device_id must be a non-empty string') unless attributes[:device_id] != "" and !attributes[:device_id].nil?
+        raise ParamError.new('timestamp must be a valid timestamp') unless valid_timestamp?(attributes[:timestamp])
 
-      url = customer_path(attributes[:id])
-
-      verify_response(request(:put, url, attributes))
+        @client.request_and_verify_response(:post, track_push_notification_event_path, attributes.merge(event: event_name))
     end
 
-    def create_customer_event(customer_id, event_name, attributes = {})
-      create_event("#{customer_path(customer_id)}/events", event_name, attributes)
+    private
+
+    def escape(val)
+      # CGI.escape is recommended for escaping, however, it doesn't correctly escape spaces.
+      Addressable::URI.encode_component(val.to_s, Addressable::URI::CharacterClasses::UNRESERVED)
     end
 
-    def create_anonymous_event(event_name, attributes = {})
-      create_event("/api/v1/events", event_name, attributes)
+    def device_path(customer_id)
+      "/api/v1/customers/#{escape(customer_id)}/devices"
     end
 
-    def create_event(url, event_name, attributes = {})
-      body = { :name => event_name, :data => attributes }
-      body[:timestamp] = attributes[:timestamp] if valid_timestamp?(attributes[:timestamp])
-      verify_response(request(:post, url, body))
+    def device_id_path(customer_id, device_id)
+      "/api/v1/customers/#{escape(customer_id)}/devices/#{escape(device_id)}"
     end
 
     def customer_path(id)
-      "/api/v1/customers/#{id}"
+      "/api/v1/customers/#{escape(id)}"
     end
 
     def suppress_path(customer_id)
-      "/api/v1/customers/#{customer_id}/suppress"
+      "/api/v1/customers/#{escape(customer_id)}/suppress"
     end
 
     def unsuppress_path(customer_id)
-      "/api/v1/customers/#{customer_id}/unsuppress"
+      "/api/v1/customers/#{escape(customer_id)}/unsuppress"
     end
 
-    def valid_timestamp?(timestamp)
-      timestamp && timestamp.is_a?(Integer) && timestamp > 999999999 && timestamp < 100000000000
+    def track_push_notification_event_path
+        "/push/events"
     end
 
+    def create_or_update(attributes = {})
+      attributes = Hash[attributes.map { |(k,v)| [ k.to_sym, v ] }]
+      raise MissingIdAttributeError.new("Must provide a customer id") if is_empty?(attributes[:id])
 
-    def verify_response(response)
-      if response.code.to_i >= 200 && response.code.to_i < 300
-        response
-      else
-        raise InvalidResponse.new("Customer.io API returned an invalid response: #{response.code}", response)
-      end
+      url = customer_path(attributes[:id])
+      @client.request_and_verify_response(:put, url, attributes)
     end
 
-    def extract_attributes(args)
-      hash = args.last.is_a?(Hash) ? args.pop : {}
-      hash.inject({}){ |hash, (k,v)| hash[k.to_sym] = v; hash }
+    def create_customer_event(customer_id, event_name, attributes = {})
+      create_event(
+        url: "#{customer_path(customer_id)}/events",
+        event_name: event_name,
+        attributes: attributes
+      )
     end
 
-    def request(method, path, body = nil, headers = {})
-      uri = URI.join(@base_uri, path)
-
-      session = Net::HTTP.new(uri.host, uri.port)
-      session.use_ssl = (uri.scheme == 'https')
-      session.open_timeout = @timeout
-      session.read_timeout = @timeout
-
-      req = request_class(method).new(uri.path)
-      req.initialize_http_header(headers)
-      req.basic_auth @username, @password
+    def create_anonymous_event(anonymous_id, event_name, attributes = {})
+      create_event(
+        url: "/api/v1/events",
+        event_name: event_name,
+        anonymous_id: anonymous_id,
+        attributes: attributes
+      )
+    end
 
-      add_request_body(req, body) unless body.nil?
+    def create_event(url:, event_name:, anonymous_id: nil, attributes: {})
+      body = { :name => event_name, :data => attributes }
+      body[:timestamp] = attributes[:timestamp] if valid_timestamp?(attributes[:timestamp])
+      body[:anonymous_id] = anonymous_id unless anonymous_id.nil?
 
-      session.start do |http|
-        http.request(req)
-      end
+      @client.request_and_verify_response(:post, url, body)
     end
 
-    def request_class(method)
-      case method
-      when :post
-        Net::HTTP::Post
-      when :put
-        Net::HTTP::Put
-      when :delete
-        Net::HTTP::Delete
-      else
-        raise InvalidRequest.new("Invalid request method #{method.inspect}")
-      end
+    def valid_timestamp?(timestamp)
+      timestamp && timestamp.is_a?(Integer) && timestamp > 999999999 && timestamp < 100000000000
     end
 
-    def add_request_body(req, body)
-      if @json
-        req.add_field('Content-Type', 'application/json')
-        req.body = MultiJson.dump(body)
-      else
-        req.add_field('Content-Type', 'application/x-www-form-urlencoded')
-        req.body = ParamEncoder.to_params(body)
-      end
+    def is_empty?(val)
+      val.nil? || (val.is_a?(String) && val.strip == "")
     end
   end
 end

data/lib/customerio/regions.rb

@@ -0,0 +1,11 @@
+require 'net/http'
+require 'multi_json'
+
+module Customerio
+  module Regions
+    Region = Struct.new(:track_url, :api_url)
+
+    US = Customerio::Regions::Region.new('https://track.customer.io', 'https://api.customer.io').freeze
+    EU = Customerio::Regions::Region.new('https://track-eu.customer.io', 'https://api-eu.customer.io').freeze
+  end
+end

data/lib/customerio/requests/send_email_request.rb

@@ -0,0 +1,49 @@
+require 'base64'
+
+module Customerio
+  class SendEmailRequest
+    attr_reader :message
+
+    def initialize(opts)
+      @message = opts.delete_if { |field| invalid_field?(field) }
+      @message[:attachments] = {}
+      @message[:headers] = {}
+    end
+
+    def attach(name, data, encode: true)
+      raise "attachment #{name} already exists" if @message[:attachments].has_key?(name)
+      @message[:attachments][name] = encode ? Base64.strict_encode64(data) : data
+    end
+
+    private
+
+    REQUIRED_FIELDS = %i(to identifiers)
+
+    OPTIONAL_FIELDS = %i(
+      transactional_message_id
+      message_data
+      headers
+      preheader
+      from
+      reply_to
+      bcc
+      subject
+      body
+      plaintext_body
+      amp_body
+      fake_bcc
+      disable_message_retention
+      send_to_unsubscribed
+      tracked
+      queue_draft
+    )
+
+    def invalid_field?(field)
+      !REQUIRED_FIELDS.include?(field) && !OPTIONAL_FIELDS.include?(field)
+    end
+
+    def encode(data)
+      Base64.strict_encode64(data)
+    end
+  end
+end

data/lib/customerio/version.rb

@@ -1,3 +1,3 @@
 module Customerio
-  VERSION = "2.1.0"
+  VERSION = "4.0.0"
 end

data/spec/api_client_spec.rb

@@ -0,0 +1,172 @@
+require 'spec_helper'
+require 'multi_json'
+require 'base64'
+require 'tempfile'
+
+describe Customerio::APIClient do
+  let(:app_key) { "appkey" }
+
+  let(:client)   { Customerio::APIClient.new(app_key) }
+  let(:response) { double("Response", code: 200) }
+
+  def api_uri(path)
+    "https://api.customer.io#{path}"
+  end
+
+  def request_headers
+    { 'Authorization': "Bearer #{app_key}", 'Content-Type': 'application/json' }
+  end
+
+  def json(data)
+    MultiJson.dump(data)
+  end
+
+  it "the base client is initialised with the correct values when no region is passed in" do
+    app_key = "appkey"
+
+    expect(Customerio::BaseClient).to(
+      receive(:new)
+        .with(
+          { app_key: app_key },
+          {
+            region: Customerio::Regions::US,
+            url: Customerio::Regions::US.api_url
+          }
+        )
+    )
+
+    client = Customerio::APIClient.new(app_key)
+  end
+
+  it "raises an error when an incorrect region is passed in" do
+    expect {
+      Customerio::APIClient.new("appkey", region: :au)
+    }.to raise_error /region must be an instance of Customerio::Regions::Region/
+  end
+
+  [Customerio::Regions::US, Customerio::Regions::EU].each do |region|
+    it "the base client is initialised with the correct values when the region \"#{region}\" is passed in" do
+      app_key = "appkey"
+
+      expect(Customerio::BaseClient).to(
+        receive(:new)
+          .with(
+            { app_key: app_key },
+            {
+              region: region,
+              url: region.api_url
+            }
+          )
+      )
+
+      client = Customerio::APIClient.new(app_key, { region: region })
+    end
+  end
+
+  describe "#send_email" do
+    it "sends a POST request to the /api/send/email path" do
+      req = Customerio::SendEmailRequest.new(
+        identifiers: {
+          id: 'c1',
+        },
+        transactional_message_id: 1,
+      )
+
+      stub_request(:post, api_uri('/v1/send/email'))
+        .with(headers: request_headers, body: req.message)
+        .to_return(status: 200, body: { delivery_id: 1 }.to_json, headers: {})
+
+      client.send_email(req).should eq({ "delivery_id" => 1 })
+    end
+
+    it "handles validation failures (400)" do
+      req = Customerio::SendEmailRequest.new(
+        identifiers: {
+          id: 'c1',
+        },
+        transactional_message_id: 1,
+      )
+
+      err_json = { meta: { error: "example error" } }.to_json
+
+      stub_request(:post, api_uri('/v1/send/email'))
+        .with(headers: request_headers, body: req.message)
+        .to_return(status: 400, body: err_json, headers: {})
+
+      lambda { client.send_email(req) }.should(
+        raise_error(Customerio::InvalidResponse) { |error|
+          error.message.should eq "example error"
+          error.code.should eq "400"
+        }
+      )
+    end
+
+    it "handles other failures (5xx)" do
+      req = Customerio::SendEmailRequest.new(
+        identifiers: {
+          id: 'c1',
+        },
+        transactional_message_id: 1,
+      )
+
+      stub_request(:post, api_uri('/v1/send/email'))
+        .with(headers: request_headers, body: req.message)
+        .to_return(status: 500, body: "Server unavailable", headers: {})
+
+      lambda { client.send_email(req) }.should(
+        raise_error(Customerio::InvalidResponse) { |error|
+          error.message.should eq "Server unavailable"
+          error.code.should eq "500"
+        }
+      )
+    end
+
+    it "allows attaching file content without encoding" do
+      content = 'sample content'
+
+      req = Customerio::SendEmailRequest.new(
+        customer_id: 'c1',
+        transactional_message_id: 1,
+      )
+
+      req.attach('test', content, encode: false)
+      req.message[:attachments]['test'].should eq content
+
+      stub_request(:post, api_uri('/v1/send/email'))
+        .with(headers: request_headers, body: req.message)
+        .to_return(status: 200, body: { delivery_id: 1 }.to_json, headers: {})
+
+      client.send_email(req)
+    end
+
+    it "allows attaching files with encoding (default)" do
+      content = 'sample content'
+
+      req = Customerio::SendEmailRequest.new(
+        customer_id: 'c1',
+        transactional_message_id: 1,
+      )
+
+      req.attach('test', content)
+      req.message[:attachments]['test'].should eq Base64.strict_encode64(content)
+
+      stub_request(:post, api_uri('/v1/send/email'))
+        .with(headers: request_headers, body: req.message)
+        .to_return(status: 200, body: { delivery_id: 1 }.to_json, headers: {})
+
+      client.send_email(req)
+    end
+
+    it "raises error when attaching the same key again" do
+      req = Customerio::SendEmailRequest.new(
+        customer_id: 'c1',
+        transactional_message_id: 1,
+      )
+
+      req.attach('test', 'test-content')
+
+      lambda { req.attach('test', '') }.should raise_error(/attachment test already exists/)
+      req.message[:attachments].should eq({ "test" => Base64.strict_encode64("test-content") })
+    end
+  end
+end