insightly 0.1.1

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2012 r26D, LLC and Dirk Elmendorf
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+

data/README.rdoc

@@ -0,0 +1,53 @@
+insightly
+=========
+
+This is a rest client library to handle talking to http://Insight.ly
+
+The official API for Insigh.ly was released on August 12, 2012.  This library is in the very early stages of implementing access to everything expose in
+that API.  The focus is primarily on opportunities and tasks.
+
+Getting Started
+=========
+
+Besides including the gem you need to use the Configuration class to set your API key.
+
+```ruby
+  Insightly::Configuration.api_key = "XXX-XXX-XXX-XXXX"
+```
+
+This key is provided to you in your User Settings section of Insight.ly.
+
+
+Custom Fields
+===========
+
+Some of the resources allow you to have custom fields. They are returned as number fields (c.f. OPPORTUNITY_FIELD_1).  You can call them directly in your code by
+that name.
+
+```ruby
+opportunity = Insightly::Opportunity.new(1000)
+opportunity.opportunity_field_1 = "Ron Campbell"
+```
+
+To make your code more readable, you can add in labels for those fields so you can refer to them more readable. The fields are lined up based on the order they are
+provided to the setting. For example, Opportunities support 10 custom fields. You can provide up to 10 labels to match all 10 fields. You can set this up in the same place
+you set your API key.
+
+```ruby
+Insightly::Configuration.custom_fields_for_opportunities(:person_who_referred_them, :where_they_saw_the_ad)
+opportunity = Insightly::Opportunity.new(1000)
+opportunity.opportunity_field_1 = "Ron Campbell"
+opportunity.person_who_referred_them == "Ron Campbell"
+```
+
+Opportunity State Reasons
+========
+
+The API allows you to change the state of an opportunity directly by modifying the OPPORTUNITY_STATE field. This doesn't store the reason
+that the opportunity state was changed.  In order to store the reason, you have to PUT to OpportunityStateChange with a valid OpportunityStateReason.
+OpportunityStateReasons can only be created manually in the web interface and then referred to via the API.
+
+This is important if you want to have it show you the state changes in the Opportuity details. Direct modifications don't create a log entry.
+Whereas the log entry is created if you do create them. In order for your code to work, you need to make sure you have valid Opportunity State Reasons for all the states.
+
+We default to creating two for open -  "Created by API", and "Reopened by API". This allows us to set those as reasons if they exist.

data/insightly.gemspec

@@ -0,0 +1,20 @@
+$:.push File.expand_path("../lib", __FILE__)
+require 'insightly/version'
+
+Gem::Specification.new do |s|
+  s.name = "insightly"
+  s.summary = "Insight.ly Ruby Client Library"
+  s.description = "Ruby library for integrating with http://Insight.ly"
+  s.version = Insightly::Version::String
+  s.authors = ["Dirk Elmendorf","r26D"]
+  s.email = "code@r26d.com"
+  s.homepage = "https://github.com/r26D/insightly"
+  s.has_rdoc = false
+  s.files = Dir.glob ["README.rdoc", "LICENSE", "{lib,spec}/**/*.rb", "lib/**/*.crt", "*.gemspec"]
+  s.add_dependency "builder", ">= 2.0.0"
+  s.add_dependency "json", ">= 1.7.5"
+  s.add_dependency "rest-client", ">=1.6.7"
+  s.add_dependency "logger", ">=1.2.8"
+  s.add_dependency "active_support", ">=3.0.0"
+  s.add_dependency "i18n", ">=0.6.1"
+end

data/lib/insightly.rb

@@ -0,0 +1,14 @@
+require 'json'
+require 'rest-client'
+require 'logger'
+require 'insightly/configuration'
+require "active_support/core_ext"  #Needed for Hash.from_xml
+
+require 'insightly/base'
+require 'insightly/read_write'
+require 'insightly/read_only'
+require 'insightly/task'
+require 'insightly/task_link'
+require 'insightly/comment'
+require 'insightly/opportunity_state_reason'
+require 'insightly/opportunity'

data/lib/insightly/base.rb

@@ -0,0 +1,123 @@
+#METODO only allow build to set fields that are part of the API fields
+#METODO make a distinction between fields that you can set and save and ones you can only read - like DATE_UPDATED_UTC
+
+
+#METODO Build and deploy a gem of this code
+module Insightly
+  class Base
+
+    class << self
+      attr_accessor :api_fields,:url_base
+    end
+    self.api_fields = []
+
+
+    def self.custom_fields(*args)
+
+      args.each_with_index do |method, index|
+        next if method.nil? or method == ""
+        method_name = method.to_s.downcase.to_sym
+        send :define_method, method_name do
+          @data["#{self.class.const_get(:CUSTOM_FIELD_PREFIX)}_#{index+1}"]
+        end
+        method_name = "#{method.to_s.downcase}=".to_sym
+        send :define_method, method_name do |value|
+          @data["#{self.class.const_get(:CUSTOM_FIELD_PREFIX)}_#{index+1}"] = value
+        end
+      end
+    end
+
+    def self.api_field(*args)
+      args.each do |field|
+        self.api_fields = [] if !self.api_fields
+        self.api_fields << field
+        method_name = field.downcase.to_sym
+        send :define_method, method_name do
+          @data[field]
+        end
+        method_name = "#{field.downcase}=".to_sym
+        send :define_method, method_name do |value|
+          @data[field] = value
+        end
+      end
+    end
+
+    def initialize(id = nil)
+      @data = {}
+      load(id) if id
+    end
+
+
+    def url_base
+      self.class.url_base
+    end
+    def remote_id
+      raise ScriptError, "This should be overridden in the subclass"
+    end
+
+    def load(id)
+      @data = get_collection("#{url_base}/#{id}")
+      self
+    end
+
+    def reload
+      load(remote_id)
+    end
+
+    def build(data)
+      @data = data
+      self
+    end
+
+    def self.build(data)
+      self.new.build(data)
+    end
+
+    def ==(other)
+      self.remote_data == other.remote_data
+    end
+
+    def remote_data
+      @data
+    end
+
+    def process(result, content_type)
+      if content_type == :json
+        JSON.parse(result.to_str)
+      elsif content_type == :xml
+        Hash.from_xml(result.to_str)
+      else
+        result
+      end
+    end
+
+    def config
+      Insightly::Configuration.instantiate
+    end
+
+    def get_collection(path, content_selector = :json)
+      if content_selector == :xml_raw
+        content_type = :xml
+      else
+        content_type = content_selector
+      end
+      response = RestClient::Request.new(:method => :get,
+                                         :url => "#{config.endpoint}/#{path.to_s}",
+                                         :user => config.api_key,
+                                         :password => "",
+                                         :headers => {:accept => content_type, :content_type => content_type}).execute
+      process(response, content_selector)
+    end
+
+    def self.all
+      item = self.new
+      list = []
+      item.get_collection(item.url_base).each do |d|
+        list << self.new.build(d)
+      end
+      list
+    end
+
+
+  end
+end

data/lib/insightly/comment.rb

@@ -0,0 +1,56 @@
+#METODO Add support for FileAttachment xml
+module Insightly
+  class Comment < ReadWrite
+    URL_BASE = "Comments"
+
+    api_field "COMMENT_ID",
+              "BODY",
+              "OWNER_USER_ID",
+              "DATE_UPDATED_UTC",
+              "DATE_CREATED_UTC",
+              "FILE_ATTACHMENTS"
+
+    def remote_id
+      comment_id
+    end
+
+    def load_from_xml(xml)
+      result = Hash.from_xml(xml.to_str)
+      if result["Comment"]
+        @data = result["Comment"]
+        ["COMMENT_ID", "OWNER_USER_ID"].each { |f| field_to_i(f) }
+        @data.delete("xmlns:xsi")
+        @data.delete('xmlns:xsd')
+      end
+      self
+    end
+
+    def to_xml
+      <<-END_XML
+<?xml version="1.0" encoding="utf-8"?>
+        <Comment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+        <COMMENT_ID>#{comment_id}</COMMENT_ID>
+        <BODY>#{body}</BODY>
+        <OWNER_USER_ID>#{owner_user_id}</OWNER_USER_ID>
+        <DATE_CREATED_UTC>#{date_created_utc}</DATE_CREATED_UTC>
+        <DATE_UPDATED_UTC>#{date_updated_utc}</DATE_UPDATED_UTC>
+        <FILE_ATTACHMENTS></FILE_ATTACHMENTS>
+        </Comment>
+      END_XML
+    end
+
+    def load(id)
+      load_from_xml(get_collection("#{url_base}/#{id}", :xml_raw))
+
+    end
+
+    def save
+      put_collection("#{url_base}", to_xml, :xml_raw)
+      self
+    end
+
+    def field_to_i(field)
+      @data[field] = @data[field].to_i if  @data[field]
+    end
+  end
+end

data/lib/insightly/configuration.rb

@@ -0,0 +1,81 @@
+#This file is based heavily off of the Braintree::Configuration
+#Copyright (c) 2009-2010 Braintree Payment Solutions
+
+module Insightly
+  class ConfigurationError < ::StandardError;
+     def initialize(setting, message) # :nodoc:
+       super "Insightly::Configuration.#{setting} #{message}"
+     end
+   end
+  class Configuration
+    API_VERSION = "v1" # :nodoc:
+    DEFAULT_ENDPOINT = "https://api.insight.ly/v1" # :nodoc:
+
+    class << self
+      attr_writer :custom_user_agent, :endpoint, :logger, :api_key
+    end
+    attr_reader :endpoint, :custom_user_agent, :api_key
+
+    def self.expectant_reader(*attributes) # :nodoc:
+      attributes.each do |attribute|
+        (class << self; self; end).send(:define_method, attribute) do
+          attribute_value = instance_variable_get("@#{attribute}")
+          raise ConfigurationError.new(attribute.to_s, "needs to be set") unless attribute_value
+          attribute_value
+        end
+      end
+    end
+    expectant_reader :api_key
+
+    def self.instantiate # :nodoc:
+      config = new(
+        :custom_user_agent => @custom_user_agent,
+        :endpoint => @endpoint,
+        :logger => logger,
+        :api_key => api_key
+      )
+    end
+
+    def self.custom_fields_for_opportunities(*args)
+      Insightly::Opportunity.custom_fields(*args)
+    end
+
+    def self.logger
+      @logger ||= _default_logger
+    end
+
+    def initialize(options = {})
+      [:endpoint, :api_key, :custom_user_agent, :logger].each do |attr|
+        instance_variable_set "@#{attr}", options[attr]
+      end
+    end
+
+    def api_version # :nodoc:
+      API_VERSION
+    end
+
+    def endpoint
+      @endpoint || DEFAULT_ENDPOINT
+    end
+
+    def logger
+      @logger ||= self.class._default_logger
+    end
+
+    def user_agent # :nodoc:
+      base_user_agent = "Insightly Ruby Gem #{Insightly::Version::String}"
+      @custom_user_agent ? "#{base_user_agent} (#{@custom_user_agent})" : base_user_agent
+    end
+
+    def self._default_logger # :nodoc:
+      logger = Logger.new(STDOUT)
+      logger.level = Logger::INFO
+      logger
+    end
+    def self._debug_logger # :nodoc:
+      logger = Logger.new(STDOUT)
+      logger.level = Logger::DEBUG
+      logger
+    end
+  end
+end

data/lib/insightly/opportunity.rb

@@ -0,0 +1,115 @@
+
+#METODO Confirm that we can create an opportunity
+module Insightly
+  class Opportunity < ReadWrite
+    self.url_base = "Opportunities"
+    CUSTOM_FIELD_PREFIX = "OPPORTUNITY_FIELD"
+    api_field "OPPORTUNITY_FIELD_10",
+              "OPPORTUNITY_FIELD_9",
+              "OPPORTUNITY_FIELD_8",
+              "OPPORTUNITY_FIELD_7",
+              "OPPORTUNITY_FIELD_6",
+              "OPPORTUNITY_FIELD_5",
+              "OPPORTUNITY_FIELD_4",
+              "OPPORTUNITY_FIELD_3",
+              "OPPORTUNITY_FIELD_2",
+              "OPPORTUNITY_FIELD_1",
+              "VISIBLE_TO",
+              "BID_TYPE",
+              "ACTUAL_CLOSE_DATE",
+              "DATE_UPDATED_UTC",
+              "OWNER_USER_ID",
+              "BID_DURATION",
+              "BID_CURRENCY",
+              "PIPELINE_ID",
+              "CATEGORY_ID",
+              "PROBABILITY",
+              "TAGS",
+              "IMAGE_URL",
+              "BID_AMOUNT",
+              "VISIBLE_TEAM_ID",
+              "STAGE_ID",
+              "DATE_CREATED_UTC",
+              "OPPORTUNITY_STATE",
+              "FORECAST_CLOSE_DATE",
+              "OPPORTUNITY_NAME",
+              "OPPORTUNITY_ID",
+              "VISIBLE_USER_IDS",
+              "LINKS",
+              "RESPONSIBLE_USER_ID",
+              "OPPORTUNITY_DETAILS"
+
+
+    def remote_id
+      opportunity_id
+    end
+
+    def tasks
+      list = []
+      Insightly::TaskLink.search_by_opportunity_id(opportunity_id).each do |x|
+        list << Insightly::Task.new(x.task_id)
+      end
+      list
+    end
+
+
+    OpportunityStateReason::STATES.each do |s|
+
+      self.instance_eval do
+        define_method "#{s.downcase}?".to_sym do
+          self.opportunity_state == s
+        end
+
+        define_method "#{s.downcase}!".to_sym do |*args|
+          reason = args.first
+          @state_reason = nil
+          if reason
+            @state_reason = Insightly::OpportunityStateReason.find_by_state_reason(s, reason)
+          end
+
+          if @state_reason
+            put_collection("OpportunityStateChange/#{opportunity_id}", @state_reason.remote_data.to_json)
+            reload
+          else
+            #Changing state without a reason/log entry
+
+            self.opportunity_state = s
+            save
+          end
+        end
+      end
+
+    end
+
+    def self.find_by_name(name)
+      Insightly::Opportunity.all.each do |o|
+        return o if o.opportunity_name && o.opportunity_name == name
+      end
+      nil
+    end
+
+    def self.search_by_name(name)
+      list = []
+      Insightly::Opportunity.all.each do |o|
+        if o.opportunity_name && o.opportunity_name.match(name)
+          list << o
+        end
+      end
+      list
+    end
+
+    def save
+      creating = remote_id ? false : true
+
+      super
+      if creating
+        @state_reason = Insightly::OpportunityStateReason.find_by_state_reason("Open", "Created by API")
+
+        if @state_reason
+          put_collection("OpportunityStateChange/#{opportunity_id}", @state_reason.remote_data.to_json)
+        end
+      end
+
+    end
+  end
+end