intercom 0.0.3 → 0.0.4

data/README.rdoc

@@ -1 +1,49 @@
-Ruby bindings for the Intercom API.
+Ruby bindings for the Intercom API (https://api.intercom.io). See http://docs.intercom.io/api for more details.
+
+Yardoc is available at http://rubydoc.info/github/intercom/intercom-ruby/master/frames
+
+== Installation
+    gem install intercom
+
+Using bundler:
+
+    gem 'intercom'
+
+== Basic Usage
+
+=== Configure your access credentials
+
+    Intercom.app_id = "my_app_iddd"
+    Intercom.api_key = "my-super-crazy-api-key"
+
+=== Resources
+
+The API supports:
+
+    POST,PUT,GET https://api.intercom.io/v1/users
+    POST,PUT,GET https://api.intercom.io/v1/users/messages
+    POST https://api.intercom.io/v1/users/impressions
+
+==== Users
+
+    user = Intercom::User.find(:email => "bob@example.com")
+    user = Intercom::User.create(:email => "bob@example.com", :name => "Bob Smith")
+    user = Intercom::User.new(params)
+    user.save
+
+==== Messages
+
+    Intercom::Message.create(:email => "bob@example.com", :body => "Example message from bob@example.com to your application on Intercom.")
+    Intercom::Message.find(:email => "bob@example.com", :thread_id => 123)
+    Intercom::Message.find_all(:email => "bob@example.com")
+    Intercom::Message.mark_as_read(:email => "bob@example.com", :thread_id => 123)
+
+==== Impressions
+
+    Intercom::Impression.create(:email => "bob@example.com", :location => "/path/in/my/app", :user_ip => "1.2.3.4", :user_agent => "my-savage-iphone-app-0.1"
+
+=== Errors
+
+    Intercom::AuthenticationError
+    Intercom::ServerError
+    Intercom::ResourceNotFound

data/Rakefile

@@ -16,11 +16,4 @@ Rake::TestTask.new("spec:integration") do |spec|
 end
 
 task :spec => "spec:unit"
-
-require 'rdoc/task'
-RDoc::Task.new do |rd|
-  rd.main = "README.rdoc"
-  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
-end
-
 task :default => :spec

data/intercom.gemspec

@@ -20,7 +20,6 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency "rest-client"
   s.add_development_dependency 'minitest'
-  s.add_development_dependency 'rdoc'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'mocha'
 end

data/lib/intercom.rb

@@ -27,6 +27,8 @@ module Intercom
   ##
   # 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>)
+  # @param [String] app_id
+  # @return [String]
   def self.app_id=(app_id)
     @app_id = app_id
   end
@@ -34,6 +36,8 @@ module Intercom
   ##
   # Set the api key to gain access to your application data.
   # When logged into your intercom console, you can view/create api keys in the settings menu
+  # @param [String] api_key
+  # @return [String]
   def self.api_key=(api_key)
     @api_key = api_key
   end
@@ -107,15 +111,16 @@ module Intercom
     @hostname = override
   end
 
-  #
   # Raised when the credentials you provide don't match a valid account on Intercom.
   # Check that you have set <b>Intercom.app_id=</b> and <b>Intercom.api_key=</b> correctly.
   class AuthenticationError < StandardError;
   end
 
+  # Raised when something does wrong on within the Intercom API service.
   class ServerError < StandardError;
   end
 
+  # Raised when requesting resources on behalf of a user that doesn't exist in your application on Intercom.
   class ResourceNotFound < StandardError;
   end
 end

data/lib/intercom/impression.rb

@@ -7,6 +7,8 @@ module Intercom
   #
   # An impressions contains user_ip, user_agent and location.
   #
+  # == Examples
+  #
   #  impression = Intercom::Impression.create(:email => "person@example.com", :location => "/pricing/upgrade",
   #                                           :user_ip => '1.2.3.4', :user_agent => "my-service-iphone-app-1.2")
   # The impression response will contain {#unread_messages}

data/lib/intercom/message_thread.rb

@@ -1,125 +1,161 @@
 require 'intercom/user_resource'
 
 module Intercom
-  ##
-  # object representing a conversation with a user
+  # A conversation with a user. Either started by the users sending a message to your application using Intercom, or by an Admin sending a message to the user.
+  # == Examples
+  #
+  # Fetching all {MessageThread}'s for a user
+  #    message_threads = Intercom::MessageThread.find_all(:email => "bob@example.com")
+  #    message_threads.size
+  #    message_thread = message_threads[0]
+  #
+  # Fetching a particular {MessageThread}
+  #    message_thread = Intercom::MessageThread.find(:email => "bob@example.com", :thread_id => 123)
+  #    message_thread.messages.map{|message| message.html }
+  #
+  # Creating a {MessageThread} on behalf of a user:
+  #    message_thread = Intercom::MessageThread.create(:email => "bob@example.com", :body => "Hello, I need some help....")
+  #
   class MessageThread < UserResource
     include UnixTimestampUnwrapper
 
-    ##
     # Finds a particular Message identified by thread_id
+    # @return [Message]
     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
+    # @return [Array<Message>]
     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
+    # @return [Message]
     def self.create(params)
       requires_parameters(params, %W(body))
       MessageThread.new(params).save
     end
 
-    ##
     # Marks a message (identified by thread_id) as read
+    # @return [Message]
     def self.mark_as_read(params)
       requires_parameters(params, %W(thread_id))
       MessageThread.new({"read" => true}.merge(params)).save(:put)
     end
 
+    # @return [Message]
     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
+    # Set the content of the message for new message creation.
+    # @param [String] body of the message. Supports markdown syntax
+    # @return [String]
     def body=(body)
       @attributes["body"] = body
     end
 
-    def body
-      @attributes["body"]
-    end
-
+    # @return [Time] when this {MessageThread} was created
     def created_at
       time_at("created_at")
     end
 
+    # @return [Time] when the last update to this {MessageThread} happened
     def updated_at
       time_at("updated_at")
     end
 
+    # @return [Integer]
+    # @param [Integer thread_id]
     def thread_id=(thread_id)
       @attributes["thread_id"] = thread_id
     end
 
+    # @return [Integer]
     def thread_id
       @attributes["thread_id"]
     end
 
+    # @return [Boolean]
+    # @param [Boolean] read whether the latest revision of the thread has been read by the user
     def read=(read)
       @attributes["read"] = read
     end
 
+    # @return [Boolean]
     def read
       @attributes["read"]
     end
 
+    # @return [Array<Message>]
     def messages
       @attributes["messages"].map {|message_hash| Message.new(message_hash)}
     end
   end
 
+  # a {MessageThread} contains multiple {Message}'s
+  #
+  # {Message}'s are a read only part of a {MessageThread}
   class Message
     include UnixTimestampUnwrapper
 
+    # Used to create a {Message} from part of the response from the API
     def initialize(params)
       @attributes = params
     end
 
+    # @return [MessageAuthor] Author, which can be either an end user, or an Admin for your application
     def from
       MessageAuthor.new(@attributes["from"])
     end
 
+    # @return [String] html markup for the message
     def html
       @attributes["html"]
     end
 
+    # @return [Time] when this message was posted
     def created_at
       time_at("created_at")
     end
   end
 
+  # each {Message} in a {MessageThread} has a {MessageAuthor}
+  #
+  # Admin authors have a name, and an avatar_path_50. Non-admin authors have a name, user_id and email.
   class MessageAuthor
+    # Used to create a {MessageAuthor} from part of the response from the API
     def initialize(params)
       @attributes = params
     end
 
+    # @return [Boolean] whether this author is an admin or not
     def admin?
       @attributes['is_admin']
     end
 
+    # @return [String] email address of the author (only available when {#admin?} is false)
     def email
       @attributes['email']
     end
 
+    # @return [String] user_id of the author (only available when {#admin?} is false)
     def user_id
       @attributes['user_id']
     end
 
+    # @return [String] url of 50x50 avatar of the admin who posted this message (only available when {#admin?} is true)
     def avatar_path_50
       @attributes['avatar_path_50']
     end
 
+    # @return [String] real name of the Admin/User, when available.
     def name
       @attributes['name']
     end

data/lib/intercom/shallow_hash.rb

@@ -1,5 +1,6 @@
 module Intercom
-  class ShallowHash < Hash #:nodoc:
+  # Sub-class of {Hash} which doesn't allow {Array} or {Hash} values.
+  class ShallowHash < Hash
     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)

data/lib/intercom/social_profile.rb

@@ -1,43 +1,24 @@
 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
+  # object representing a social profile for the User (see )http://docs.intercom.io/#SocialProfiles).
+  # Read only part of the {User} object
+  class SocialProfile
+    # @return  [String] type e.g. twitter, facebook etc.
+    attr_reader :type
+    # @return  [String] id
+    attr_reader :id
+    # @return  [String] url
+    attr_reader :url
+    # @return [String] username
+    attr_reader :username
+
+    # @private
+    def initialize(params)
+      @type = params["type"]
+      @id = params["id"]
+      @url = params["url"]
+      @username = params["username"]
     end
   end
 end

data/lib/intercom/unix_timestamp_unwrapper.rb

@@ -1,4 +1,5 @@
 module Intercom
+  # Our api returns date as unix time stamps. This module helps marshall to and from {Time} objects.
   module UnixTimestampUnwrapper
     def time_at(attribute_name)
       Time.at(@attributes[attribute_name]) if @attributes[attribute_name]

data/lib/intercom/user.rb

@@ -13,6 +13,7 @@ module Intercom
     #
     # returns Intercom::User object representing the state on our servers.
     #
+    # @return [User]
     def self.find(params)
       response = Intercom.get("users", params)
       User.from_api(response)
@@ -26,17 +27,19 @@ module Intercom
     # returns Intercom::User object representing the state on our servers.
     #
     # This operation is idempotent.
+    # @return [User]
     def self.create(params)
       User.new(params).save
     end
 
-    ##
     # instance method alternative to #create
+    # @return [User]
     def save
       response = Intercom.post("users", to_hash)
       self.update_from_api_response(response)
     end
 
+    # @return {User}
     def name
       @attributes["name"]
     end
@@ -45,6 +48,7 @@ module Intercom
       @attributes["name"]=name
     end
 
+    # @return [String]
     def last_seen_ip
       @attributes["last_seen_ip"]
     end
@@ -53,6 +57,7 @@ module Intercom
       @attributes["last_seen_ip"]=last_seen_ip
     end
 
+    # @return [String]
     def last_seen_user_agent
       @attributes["last_seen_user_agent"]
     end
@@ -61,28 +66,32 @@ module Intercom
       @attributes["last_seen_user_agent"]=last_seen_user_agent
     end
 
+    # @return [Integer]
     def relationship_score
       @attributes["relationship_score"]
     end
 
+    # @return [Integer]
     def session_count
       @attributes["session_count"]
     end
 
     ##
     # Get last time this User interacted with your application
+    # @return [Time]
     def last_impression_at
       time_at("last_impression_at")
     end
 
     ##
     # Get Time at which this User started using your application.
+    # @return [Time]
     def created_at
       time_at("created_at")
     end
 
     ##
-    # Get Time at which this User started using your application.
+    # Set Time at which this User started using your application.
     def created_at=(time)
       set_time_at("created_at", time)
     end
@@ -91,6 +100,7 @@ module Intercom
     # Get array of Intercom::SocialProfile objects attached to this Intercom::User
     #
     # See http://docs.intercom.io/#SocialProfiles for more information
+    # @return [Array<SocialProfile>]
     def social_profiles
       @social_profiles ||= [].freeze
     end
@@ -105,6 +115,7 @@ module Intercom
     #    {"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"}
+    # @return [Hash]
     def location_data
       @location_data ||= {}.freeze
     end
@@ -113,10 +124,15 @@ module Intercom
     # Get hash of custom attributes stored for this Intercom::User
     #
     # See http://docs.intercom.io/#CustomData for more information
+    # @return [Hash]
     def custom_data
       @attributes["custom_data"] ||= ShallowHash.new
     end
 
+    def custom_data=(custom_data) #:nodoc:
+      @attributes["custom_data"] = ShallowHash.new.merge(custom_data)
+    end
+
     protected
     def social_profiles=(social_profiles) #:nodoc:
       @social_profiles = social_profiles.map { |account| SocialProfile.new(account) }.freeze
@@ -125,9 +141,5 @@ module Intercom
     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

data/lib/intercom/user_resource.rb

@@ -1,6 +1,7 @@
 require 'intercom/unix_timestamp_unwrapper'
 
 module Intercom
+  # Base class for resources tied off a {User}, all of which are scoped by either the users :email or :user_id.
   class UserResource
     include UnixTimestampUnwrapper
 
@@ -8,26 +9,36 @@ module Intercom
       self.attributes = attributes
     end
 
+    # @return [Hash] hash of all the attributes in the structure they will be sent to the api
     def to_hash
       UserResource.for_wire(@attributes)
     end
 
+    # @return [String] email address
     def email
       @attributes["email"]
     end
 
+    # @param [String] email
+    # @return [String]
     def email=(email)
-      @attributes["email"]=email
+      @attributes["email"] = email
     end
 
+
+    # @return [String] user_id
     def user_id
       @attributes["user_id"]
     end
 
+    # @param [String] user_id
+    # @return [String]
     def user_id=(user_id)
       @attributes["user_id"] = user_id
     end
 
+    # updates the internal state of this {UserResource} based on the response from the API
+    # @return [UserResource] self
     def update_from_api_response(api_response)
       api_response.each do |key, value|
         setter_method = "#{key.to_s}="

data/lib/intercom/version.rb

@@ -1,3 +1,3 @@
 module Intercom #:nodoc:
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/unit/intercom/user_spec.rb

@@ -45,7 +45,7 @@ describe "Intercom::User" do
   end
 
   it "has read-only social accounts" do
-    user = Intercom::User.new(:social_profiles => [:url => "http://twitter.com/abc", "username" => "abc", "type" => "twitter"])
+    user = Intercom::User.new(:social_profiles => ["url" => "http://twitter.com/abc", "username" => "abc", "type" => "twitter"])
     user.social_profiles.size.must_equal 1
     twitter = user.social_profiles.first
     twitter.type.must_equal "twitter"

data/spec/unit/intercom_spec.rb

@@ -2,7 +2,7 @@ require "spec_helper"
 
 describe Intercom do
   it "has a version number" do
-    Intercom::VERSION.must_equal "0.0.2"
+    Intercom::VERSION.must_match /\d+\.\d+\.\d+/
   end
 
   describe "API" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: intercom
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-06 00:00:00.000000000Z
+date: 2012-03-09 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70197574767120 !ruby/object:Gem::Requirement
+  requirement: &70301913505580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70197574767120
+  version_requirements: *70301913505580
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70197574748440 !ruby/object:Gem::Requirement
+  requirement: &70301913504840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,21 +34,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70197574748440
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: &70197574686840 !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: *70197574686840
+  version_requirements: *70301913504840
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70197570625140 !ruby/object:Gem::Requirement
+  requirement: &70301913504220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,10 +45,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70197570625140
+  version_requirements: *70301913504220
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70197570614200 !ruby/object:Gem::Requirement
+  requirement: &70301913503620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -67,7 +56,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70197570614200
+  version_requirements: *70301913503620
 description: ! 'Intercom (https://www.intercom.io) is a customer relationship management
   and messaging tool for web app owners. This library wraps the api provided by Intercom.
   See http://docs.intercom.io/api for more details. '
@@ -82,7 +71,6 @@ files:
 - .gitignore
 - Gemfile
 - LICENSE
-- README.md
 - README.rdoc
 - Rakefile
 - changed.txt
@@ -136,4 +124,3 @@ test_files:
 - spec/unit/intercom/user_spec.rb
 - spec/unit/intercom_spec.rb
 - spec/unit/spec_helper.rb
-has_rdoc: 

data/README.md

@@ -1,57 +0,0 @@
-Ruby bindings for the Intercom API (https://api.intercom.io). See http://docs.intercom.io/api for more details
-
-## Install
-```
-gem install intercom
-```
-
-## Basic Usage
-
-### Configure your access credentials
-
-```
-Intercom.app_id = "my_app_iddd"
-Intercom.api_key = "my-super-crazy-api-key"
-```
-
-### Resources
-
-The API supports:
-
-```
-POST,PUT,GET https://api.intercom.io/v1/users
-POST,PUT,GET https://api.intercom.io/v1/users/messages
-POST https://api.intercom.io/v1/users/impressions
-```
-
-#### Users
-
-```ruby
-user = Intercom::User.find(:email => "bob@example.com")
-user = Intercom::User.create(params)
-user = Intercom::User.new(params)
-user.save
-```
-
-#### Messages
-
-```ruby
-Intercom::Message.create
-Intercom::Message.find
-Intercom::Message.find_all
-Intercom::Message.mark_as_read
-```
-
-#### Impressions
-
-```ruby
-Intercom::Impression.create
-```
-
-### Errors
-
-```ruby
-Intercom::AuthenticationError
-Intercom::ServerError
-Intercom::ResourceNotFound
-```