intercom 0.0.1 → 0.0.2

data/lib/intercom.rb

@@ -1,53 +1,118 @@
 require "intercom/version"
+require "intercom/user_resource"
+require "intercom/user"
+require "intercom/message_thread"
+require "intercom/impression"
 require "rest_client"
-require 'json'
+require "json"
 
+##
+# Intercom is a customer relationship management and messaging tool for web app owners
+#
+# This library provides ruby bindings for the Intercom API (https://api.intercom.io)
+#
+# == Basic Usage
+# === Configure Intercom with your access credentials
+#   Intercom.app_id = "my_app_id"
+#   Intercom.secret_key = "my_secret_key"
+# === Make requests to the API
+#   Intercom::User.find(:email => "bob@example.com")
+#
 module Intercom
+  @hostname = "api.intercom.io"
+  @protocol = "https"
+  @app_id = nil
+  @secret_key = nil
+
+  ##
+  # Set the id of the application you want to interact with.
+  # When logged into your intercom console, the app_id is in the url after /apps (eg https://www.intercom.io/apps/<app-id>)
   def self.app_id=(app_id)
     @app_id = app_id
   end
 
+  ##
+  # Set the secret key to gain access to your application data.
+  # When logged into your intercom console, you can view/create api keys in the settings menu
   def self.secret_key=(secret_key)
     @secret_key = secret_key
   end
 
-  def self.protocol
-    "https"
+
+  private
+  def self.url_for_path(path)
+    raise ArgumentError, "You must set both Intercom.app_id and Intercom.secret_key to use this client. See https://github.com/intercom/intercom for usage examples." if [@app_id, @secret_key].any?(&:nil?)
+    "#{protocol}://#{@app_id}:#{@secret_key}@#{hostname}/v1/#{path}"
   end
 
-  def self.hostname
-    "api.intercom.io"
+  def self.post(path, payload_hash)
+    execute_request(:post, path, {}, {:content_type => :json, :accept => :json}, payload_hash)
+  end
+
+  def self.put(path, payload_hash)
+    execute_request(:put, path, {}, {:content_type => :json, :accept => :json}, payload_hash)
+  end
+
+  def self.get(path, params)
+    execute_request(:get, path, params)
+  end
+
+  def self.require_email_or_user_id(params)
+    raise ArgumentError.new("Expected params Hash, got #{params.class}") unless params.is_a?(Hash)
+    raise ArgumentError.new("Either email or user_id must be specified") unless params.keys.any? { |key| %W(email user_id).include?(key.to_s) }
   end
 
   def self.execute_request(method, path, params = {}, headers = {}, payload = nil)
-    url = "https://#{@app_id}:#{@secret_key}@api.intercom.io/v1/#{path}"
-    args = {
+    method.eql?(:get) ? require_email_or_user_id(params) : require_email_or_user_id(payload)
+    args =rest_client_args(method, path, params, headers, payload)
+    begin
+      response = RestClient::Request.execute(args)
+      JSON.parse(response.body)
+    rescue RestClient::ResourceNotFound
+      raise ResourceNotFound.new
+    rescue RestClient::Unauthorized
+      raise AuthenticationError.new
+    rescue RestClient::InternalServerError
+      raise ServerError.new
+    end
+  end
+
+  def self.rest_client_args(method, path, params, headers, payload)
+    url = url_for_path(path)
+    {
         :method => method,
         :url => url,
-        :headers => {:params => params}.merge(headers),
+        :headers => {:params => params}.merge(headers).merge(:accept => :json),
         :open_timeout => 10,
-        :payload => payload,
-        :timeout => 30
+        :payload => payload.nil? ? nil : payload.to_json,
+        :timeout => 30,
+        :verify_ssl => OpenSSL::SSL::VERIFY_PEER,
+        :ssl_ca_file => File.join(File.dirname(__FILE__), 'data/cacert.pem')
     }
-    RestClient::Request.execute(args)
   end
 
-  class User
-    def initialize(response)
-      @response = response
-    end
+  def self.protocol #nodoc
+    @protocol
+  end
 
-    def self.find(params)
-      response = Intercom.execute_request(:get, "users", params)
-      User.new(response)
-    end
+  def self.protocol=(override)
+    @protocol = override
+  end
 
-    def save
-      Intercom.execute_request(:post, "users", {}, {:content_type => :json}, {"email" => "bo@example.com"}.to_json)
-    end
+  def self.hostname
+    @hostname
+  end
 
-    def method_missing(method, *args, &block)
-      @response[method.to_sym]
-    end
+  def self.hostname=(override)
+    @hostname = override
+  end
+
+  class AuthenticationError < StandardError;
+  end
+
+  class ServerError < StandardError;
+  end
+
+  class ResourceNotFound < StandardError;
   end
-end
+end

data/lib/intercom/impression.rb

@@ -0,0 +1,47 @@
+require 'intercom/user_resource'
+
+module Intercom
+
+  ##
+  # Represents a users interaction with your app (eg page view, or using a particular feature)
+  class Impression < UserResource
+    ##
+    # Records that a user has interacted with your application, including the 'location' within the app they used
+    def self.create(params)
+      Impression.new(params).save
+    end
+
+    def save
+      response = Intercom.post("users/impressions", to_hash)
+      self.update_from_api_response(response)
+    end
+
+    def user_ip=(user_ip)
+      @attributes["user_ip"] = user_ip
+    end
+
+    def user_ip
+      @attributes["user_ip"]
+    end
+
+    def location=(location)
+      @attributes["location"] = location
+    end
+
+    def location
+      @attributes["location"]
+    end
+
+    def user_agent=(user_agent)
+      @attributes["user_agent"] = user_agent
+    end
+
+    def user_agent
+      @attributes["user_agent"]
+    end
+
+    def unread_messages
+      @attributes["unread_messages"]
+    end
+  end
+end

data/lib/intercom/message_thread.rb

@@ -0,0 +1,128 @@
+require 'intercom/user_resource'
+
+module Intercom
+  ##
+  # object representing a conversation with a user
+  class MessageThread < UserResource
+    include UnixTimestampUnwrapper
+
+    ##
+    # Finds a particular Message identified by thread_id
+    def self.find(params)
+      requires_parameters(params, %W(thread_id))
+      api_response = Intercom.get("users/message_threads", params)
+      MessageThread.from_api(api_response)
+    end
+
+    ##
+    # Finds all Messages to show a particular user
+    def self.find_all(params)
+      response = Intercom.get("users/message_threads", params)
+      response.map { |message| MessageThread.from_api(message) }
+    end
+
+    ##
+    # Either creates a new message from this user to your application admins, or a comment on an existing one
+    def self.create(params)
+      requires_parameters(params, %W(body))
+      MessageThread.new(params).save
+    end
+
+    ##
+    # Marks a message (identified by thread_id) as read
+    def self.mark_as_read(params)
+      requires_parameters(params, %W(thread_id))
+      MessageThread.new({"read" => true}.merge(params)).save(:put)
+    end
+
+    def save(method=:post)
+      response = Intercom.send(method, "users/message_threads", to_hash)
+      self.update_from_api_response(response)
+    end
+
+    ##
+    # Set the content of the message. Supports standard markdown syntax
+    def body=(body)
+      @attributes["body"] = body
+    end
+
+    def body
+      @attributes["body"]
+    end
+
+    def created_at
+      time_at("created_at")
+    end
+
+    def updated_at
+      time_at("updated_at")
+    end
+
+
+    def thread_id=(thread_id)
+      @attributes["thread_id"] = thread_id
+    end
+
+    def thread_id
+      @attributes["thread_id"]
+    end
+
+    def read=(read)
+      @attributes["read"] = read
+    end
+
+    def read
+      @attributes["read"]
+    end
+
+    def messages
+      @attributes["messages"].map {|message_hash| Message.new(message_hash)}
+    end
+  end
+
+  class Message
+    include UnixTimestampUnwrapper
+
+    def initialize(params)
+      @attributes = params
+    end
+
+    def from
+      MessageAuthor.new(@attributes["from"])
+    end
+
+    def html
+      @attributes["html"]
+    end
+
+    def created_at
+      time_at("created_at")
+    end
+  end
+
+  class MessageAuthor
+    def initialize(params)
+      @attributes = params
+    end
+
+    def admin?
+      @attributes['is_admin']
+    end
+
+    def email
+      @attributes['email']
+    end
+
+    def user_id
+      @attributes['user_id']
+    end
+
+    def avatar_path_50
+      @attributes['avatar_path_50']
+    end
+
+    def name
+      @attributes['name']
+    end
+  end
+end

data/lib/intercom/shallow_hash.rb

@@ -0,0 +1,8 @@
+module Intercom
+  class ShallowHash < Hash #:nodoc:
+    def []=(key, value)
+      raise ArgumentError.new("custom_data does not support nested data structures (key: #{key}, value: #{value}") if value.is_a?(Array) || value.is_a?(Hash)
+      super(key, value)
+    end
+  end
+end

data/lib/intercom/social_profile.rb

@@ -0,0 +1,43 @@
+require 'intercom/user_resource'
+
+module Intercom
+  ##
+  # object representing a social profile for the User (see )http://docs.intercom.io/#SocialProfiles)
+  class SocialProfile < UserResource
+    def for_wire #:nodoc:
+      @attributes
+    end
+
+    def type
+      @attributes["type"]
+    end
+
+    def type=(type)
+      @attributes["type"]=type
+    end
+
+    def id
+      @attributes["id"]
+    end
+
+    def id=(id)
+      @attributes["id"]=id
+    end
+
+    def url
+      @attributes["url"]
+    end
+
+    def url=(url)
+      @attributes["url"]=url
+    end
+
+    def username
+      @attributes["username"]
+    end
+
+    def username=(username)
+      @attributes["username"]=username
+    end
+  end
+end

data/lib/intercom/unix_timestamp_unwrapper.rb

@@ -0,0 +1,11 @@
+module Intercom
+  module UnixTimestampUnwrapper
+    def time_at(attribute_name)
+      Time.at(@attributes[attribute_name]) if @attributes[attribute_name]
+    end
+
+    def set_time_at(attribute_name, time)
+      @attributes[attribute_name.to_s] = time.to_i
+    end
+  end
+end

data/lib/intercom/user.rb

@@ -0,0 +1,133 @@
+require 'intercom/user_resource'
+require 'intercom/shallow_hash'
+require 'intercom/social_profile'
+
+module Intercom
+  ##
+  # Represents a user of your application on Intercom.
+  class User < UserResource
+    ##
+    # Fetches an Intercom::User from our API.
+    #
+    # Calls GET https://api.intercom.io/v1/users
+    #
+    # returns Intercom::User object representing the state on our servers.
+    #
+    def self.find(params)
+      response = Intercom.get("users", params)
+      User.from_api(response)
+    end
+
+    ##
+    # Creates (or updates when a user already exists for that email/user_id) a user record on your application.
+    #
+    # Calls POST https://api.intercom.io/v1/users
+    #
+    # returns Intercom::User object representing the state on our servers.
+    #
+    # This operation is idempotent.
+    def self.create(params)
+      User.new(params).save
+    end
+
+    ##
+    # instance method alternative to #create
+    def save
+      response = Intercom.post("users", to_hash)
+      self.update_from_api_response(response)
+    end
+
+    def name
+      @attributes["name"]
+    end
+
+    def name=(name)
+      @attributes["name"]=name
+    end
+
+    def last_seen_ip
+      @attributes["last_seen_ip"]
+    end
+
+    def last_seen_ip=(last_seen_ip)
+      @attributes["last_seen_ip"]=last_seen_ip
+    end
+
+    def last_seen_user_agent
+      @attributes["last_seen_user_agent"]
+    end
+
+    def last_seen_user_agent=(last_seen_user_agent)
+      @attributes["last_seen_user_agent"]=last_seen_user_agent
+    end
+
+    def relationship_score
+      @attributes["relationship_score"]
+    end
+
+    def session_count
+      @attributes["session_count"]
+    end
+
+    ##
+    # Get last time this User interacted with your application
+    def last_impression_at
+      time_at("last_impression_at")
+    end
+
+    ##
+    # Get Time at which this User started using your application.
+    def created_at
+      time_at("created_at")
+    end
+
+    ##
+    # Get Time at which this User started using your application.
+    def created_at=(time)
+      set_time_at("created_at", time)
+    end
+
+    ##
+    # Get array of Intercom::SocialProfile objects attached to this Intercom::User
+    #
+    # See http://docs.intercom.io/#SocialProfiles for more information
+    def social_profiles
+      @social_profiles ||= [].freeze
+    end
+
+    ##
+    # Get hash of location attributes associated with this Intercom::User
+    #
+    # Possible entries: city_name, continent_code, country_code, country_name, latitude, longitude, postal_code, region_name, timezone
+    #
+    # e.g.
+    #
+    #    {"city_name"=>"Santiago", "continent_code"=>"SA", "country_code"=>"CHL", "country_name"=>"Chile",
+    #     "latitude"=>-33.44999999999999, "longitude"=>-70.6667, "postal_code"=>"", "region_name"=>"12",
+    #     "timezone"=>"Chile/Continental"}
+    def location_data
+      @location_data ||= {}.freeze
+    end
+
+    ##
+    # Get hash of custom attributes stored for this Intercom::User
+    #
+    # See http://docs.intercom.io/#CustomData for more information
+    def custom_data
+      @attributes["custom_data"] ||= ShallowHash.new
+    end
+
+    protected
+    def social_profiles=(social_profiles) #:nodoc:
+      @social_profiles = social_profiles.map { |account| SocialProfile.new(account) }.freeze
+    end
+
+    def location_data=(hash) #:nodoc:
+      @location_data = hash.freeze
+    end
+
+    def custom_data=(custom_data) #:nodoc:
+      @attributes["custom_data"] = ShallowHash.new.merge(custom_data)
+    end
+  end
+end