forecasted 0.0.1

data/lib/forecast/model.rb

@@ -0,0 +1,154 @@
+module Forecast
+  module Model
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.send :extend, ClassMethods
+    end
+
+    module InstanceMethods
+      def to_json(*args)
+        as_json(*args).to_json(*args)
+      end
+
+      def as_json(args = {})
+        inner_json = self.to_hash.stringify_keys
+        inner_json.delete("cache_version")
+        if self.class.skip_json_root?
+          inner_json
+        else
+          { self.class.json_root => inner_json }
+        end
+      end
+
+      def to_i; id; end
+
+      def ==(other)
+        other.kind_of?(self.class) && id == other.id
+      end
+
+      def impersonated_user_id
+        if respond_to?(:of_user) && respond_to?(:user_id)
+          of_user || user_id
+        elsif !respond_to?(:of_user) && respond_to?(:user_id)
+          user_id
+        elsif respond_to?(:of_user)
+          of_user
+        end
+      end
+
+      def json_root
+        self.class.json_root
+      end
+    end
+
+    module ClassMethods
+      # This sets the API path so the API collections can use them in an agnostic way
+      # @return [void]
+      def api_path(path = nil)
+        @_api_path ||= path
+      end
+
+      def skip_json_root(skip = nil)
+        @_skip_json_root ||= skip
+      end
+
+      def skip_json_root?
+        @_skip_json_root == true
+      end
+
+      def parse(json)
+        #
+        # old gem
+        # parsed = String === json ? JSON.parse(json) : json
+        # Array.wrap(parsed).map {|attrs| skip_json_root? ? new(attrs) : new(attrs[json_root])}
+        #
+
+        # parses json into a ruby hash
+        # {'projects' => [{id: 123}, {id: 456}]}
+        parsed = String === json ? JSON.parse(json) : json
+
+
+        # @todo @weston
+        # total hack
+        if parsed.keys == [json_root]
+          # single object
+          # before  # {"project"=>{"id"=>123"}}
+          # after   # {"id"=>123}
+          object_hash = parsed[json_root]
+          new(object_hash)
+        else
+          # list of objects
+          # before # {'projects' => [{id: 123}, {id: 456}]}
+          # after  # [{id: 123}, {id: 456}]
+          object_hashes = parsed.to_a[0][1]
+          return object_hashes.map {|attrs| new(attrs)}
+        end
+      end
+
+      def json_root
+        Forecast::Model::Utility.underscore(
+          Forecast::Model::Utility.demodulize(to_s))
+      end
+
+      def wrap(model_or_attrs)
+        case model_or_attrs
+        when Hashie::Mash
+          model_or_attrs
+        when Hash
+          new(model_or_attrs)
+        else
+          model_or_attrs
+        end
+      end
+
+      def delegate_methods(options)
+        raise "no methods given" if options.empty?
+        options.each do |source, dest|
+          class_eval <<-EOV
+            def #{source}
+              #{dest}
+            end
+          EOV
+        end
+      end
+    end
+
+    module Utility
+      class << self
+
+        # Both methods are shamelessly ripped from https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/inflections.rb
+
+        # Removes the module part from the expression in the string.
+        #
+        # Examples:
+        #   "ActiveRecord::CoreExtensions::String::Inflections".demodulize # => "Inflections"
+        #   "Inflections".demodulize
+        def demodulize(class_name_in_module)
+          class_name_in_module.to_s.gsub(/^.*::/, '')
+        end
+
+        # Makes an underscored, lowercase form from the expression in the string.
+        #
+        # Changes '::' to '/' to convert namespaces to paths.
+        #
+        # Examples:
+        #   "ActiveRecord".underscore         # => "active_record"
+        #   "ActiveRecord::Errors".underscore # => active_record/errors
+        #
+        # As a rule of thumb you can think of +underscore+ as the inverse of +camelize+,
+        # though there are cases where that does not hold:
+        #
+        #   "SSLError".underscore.camelize # => "SslError"
+        def underscore(camel_cased_word)
+          word = camel_cased_word.to_s.dup
+          word.gsub!(/::/, '/')
+          word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+          word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+          word.tr!("-", "_")
+          word.downcase!
+          word
+        end
+      end
+    end
+  end
+end

data/lib/forecast/project.rb

@@ -0,0 +1,37 @@
+module Forecast
+
+  # The model that contains information about a project
+  #
+  # == Fields
+  # [+id+] (READONLY) the id of the project
+  # [+name+] (REQUIRED) the name of the project
+  # [+client_id+] (REQUIRED) the client id of the project
+  # [+code+] the project code
+  # [+notes+] the project notes
+  # [+active?+] true|false whether the project is active
+  # [+billable?+] true|false where the project is billable
+  # [+budget_by+] how the budget is calculated for the project +project|project_cost|task|person|nil+
+  # [+budget+] what the budget is for the project (based on budget_by)
+  # [+bill_by+] how to bill the project +Tasks|People|Project|nil+
+  # [+hourly_rate+] what the hourly rate for the project is based on +bill_by+
+  # [+notify_when_over_budget?+] whether the project will send notifications when it goes over budget
+  # [+over_budget_notification_percentage+] what percentage of the budget the project has to be before it sends a notification. Based on +notify_when_over_budget?+
+  # [+show_budget_to_all?+] whether the project's budget is shown to employees and contractors
+  # [+basecamp_id+] (READONLY) the id of the basecamp project associated to the project
+  # [+highrise_deal_id+] (READONLY) the id of the highrise deal associated to the project
+  # [+active_task_assignments_count+] (READONLY) the number of active task assignments
+  # [+created_at+] (READONLY) when the project was created
+  # [+updated_at+] (READONLY) when the project was updated
+  class Project < Hashie::Mash
+    include Forecast::Model
+
+    api_path '/projects'
+
+    def as_json(args = {})
+      super(args).tap do |json|
+      #   json[json_root].delete("hint_earliest_record_at")
+      #   json[json_root].delete("hint_latest_record_at")
+      end
+    end
+  end
+end

data/lib/forecast/rate_limit_status.rb

@@ -0,0 +1,23 @@
+# module Harvest
+
+#   # The model that contains the information about the user's rate limit
+#   #
+#   # == Fields
+#   # [+last_access_at+]  The last registered request
+#   # [+count+] The current number of requests registered
+#   # [+timeframe_limit+] The amount of seconds before a rate limit refresh occurs
+#   # [+max_calls+] The number of requests you can make within the +timeframe_limit+
+#   # [+lockout_seconds+] If you exceed the rate limit, how long you will be locked out from Harvest
+#   class RateLimitStatus < Hashie::Mash
+#     include Harvest::Model
+
+#     skip_json_root true
+
+#     # Returns true if the user is over their rate limit
+#     # @return [Boolean]
+#     # @see http://www.getharvest.com/api
+#     def over_limit?
+#       count > max_calls
+#     end
+#   end
+# end

data/lib/forecast/task.rb

@@ -0,0 +1,22 @@
+# module Harvest
+
+#   # The model that contains information about a task
+#   #
+#   # == Fields
+#   # [+id+] (READONLY) the id of the task
+#   # [+name+] (REQUIRED) the name of the task
+#   # [+billable+] whether the task is billable by default
+#   # [+deactivated+] whether the task is deactivated
+#   # [+hourly_rate+] what the default hourly rate for the task is
+#   # [+default?+] whether to add this task to new projects by default
+#   class Task < Hashie::Mash
+#     include Harvest::Model
+
+#     api_path '/tasks'
+#     delegate_methods :default? => :is_default
+
+#     def active?
+#       !deactivated
+#     end
+#   end
+# end

data/lib/forecast/time_entry.rb

@@ -0,0 +1,25 @@
+# module Harvest
+#   class TimeEntry < Hashie::Mash
+#     include Harvest::Model
+
+#     skip_json_root true
+#     delegate_methods(:closed? => :is_closed,
+#                      :billed? => :is_billed)
+
+#     def initialize(args = {}, _ = nil)
+#       args = args.to_hash.stringify_keys
+#       self.spent_at = args.delete("spent_at") if args["spent_at"]
+#       super
+#     end
+
+#     def spent_at=(date)
+#       self["spent_at"] = Date.parse(date.to_s)
+#     end
+
+#     def as_json(args = {})
+#       super(args).to_hash.stringify_keys.tap do |hash|
+#         hash.update("spent_at" => (spent_at.nil? ? nil : spent_at.xmlschema))
+#       end
+#     end
+#   end
+# end

data/lib/forecast/timezones.rb

@@ -0,0 +1,130 @@
+module Forecast
+  # shamelessly ripped from Rails: http://github.com/rails/rails/blob/master/activesupport/lib/active_support/values/time_zone.rb
+  module Timezones
+    MAPPING = {
+        "pacific/midway"                  =>   "Midway Island",
+        "pacific/pago_pago"               =>   "Samoa",
+        "pacific/honolulu"                =>   "Hawaii",
+        "america/juneau"                  =>   "Alaska",
+        "america/los_angeles"             =>   "Pacific Time (US & Canada)",
+        "america/tijuana"                 =>   "Tijuana",
+        "america/denver"                  =>   "Mountain Time (US & Canada)",
+        "america/phoenix"                 =>   "Arizona",
+        "america/chihuahua"               =>   "Chihuahua",
+        "america/mazatlan"                =>   "Mazatlan",
+        "america/chicago"                 =>   "Central Time (US & Canada)",
+        "america/regina"                  =>   "Saskatchewan",
+        "america/mexico_city"             =>   "Mexico City",
+        "america/monterrey"               =>   "Monterrey",
+        "america/guatemala"               =>   "Central America",
+        "america/new_york"                =>   "Eastern Time (US & Canada)",
+        "america/indiana/indianapolis"    =>   "Indiana (East)",
+        "america/bogota"                  =>   "Bogota",
+        "america/lima"                    =>   "Lima",
+        "america/halifax"                 =>   "Atlantic Time (Canada)",
+        "america/caracas"                 =>   "Caracas",
+        "america/la_paz"                  =>   "La Paz",
+        "america/santiago"                =>   "Santiago",
+        "america/st_johns"                =>   "Newfoundland",
+        "america/sao_paulo"               =>   "Brasilia",
+        "america/argentina/buenos_aires"  =>   "Buenos Aires",
+        "america/argentina/san_juan"      =>   "Georgetown",
+        "america/godthab"                 =>   "Greenland",
+        "atlantic/south_georgia"          =>   "Mid-Atlantic",
+        "atlantic/azores"                 =>   "Azores",
+        "atlantic/cape_verde"             =>   "Cape Verde Is.",
+        "europe/dublin"                   =>   "Dublin",
+        "europe/lisbon"                   =>   "Lisbon",
+        "europe/london"                   =>   "London",
+        "africa/casablanca"               =>   "Casablanca",
+        "africa/monrovia"                 =>   "Monrovia",
+        "etc/utc"                         =>   "UTC",
+        "europe/belgrade"                 =>   "Belgrade",
+        "europe/bratislava"               =>   "Bratislava",
+        "europe/budapest"                 =>   "Budapest",
+        "europe/ljubljana"                =>   "Ljubljana",
+        "europe/prague"                   =>   "Prague",
+        "europe/sarajevo"                 =>   "Sarajevo",
+        "europe/skopje"                   =>   "Skopje",
+        "europe/warsaw"                   =>   "Warsaw",
+        "europe/zagreb"                   =>   "Zagreb",
+        "europe/brussels"                 =>   "Brussels",
+        "europe/copenhagen"               =>   "Copenhagen",
+        "europe/madrid"                   =>   "Madrid",
+        "europe/paris"                    =>   "Paris",
+        "europe/amsterdam"                =>   "Amsterdam",
+        "europe/berlin"                   =>   "Berlin",
+        "europe/rome"                     =>   "Rome",
+        "europe/stockholm"                =>   "Stockholm",
+        "europe/vienna"                   =>   "Vienna",
+        "africa/algiers"                  =>   "West Central Africa",
+        "europe/bucharest"                =>   "Bucharest",
+        "africa/cairo"                    =>   "Cairo",
+        "europe/helsinki"                 =>   "Helsinki",
+        "europe/kiev"                     =>   "Kyev",
+        "europe/riga"                     =>   "Riga",
+        "europe/sofia"                    =>   "Sofia",
+        "europe/tallinn"                  =>   "Tallinn",
+        "europe/vilnius"                  =>   "Vilnius",
+        "europe/athens"                   =>   "Athens",
+        "europe/istanbul"                 =>   "Istanbul",
+        "europe/minsk"                    =>   "Minsk",
+        "asia/jerusalem"                  =>   "Jerusalem",
+        "africa/harare"                   =>   "Harare",
+        "africa/johannesburg"             =>   "Pretoria",
+        "europe/moscow"                   =>   "Moscow",
+        "asia/kuwait"                     =>   "Kuwait",
+        "asia/riyadh"                     =>   "Riyadh",
+        "africa/nairobi"                  =>   "Nairobi",
+        "asia/baghdad"                    =>   "Baghdad",
+        "asia/tehran"                     =>   "Tehran",
+        "asia/muscat"                     =>   "Muscat",
+        "asia/baku"                       =>   "Baku",
+        "asia/tbilisi"                    =>   "Tbilisi",
+        "asia/yerevan"                    =>   "Yerevan",
+        "asia/kabul"                      =>   "Kabul",
+        "asia/yekaterinburg"              =>   "Ekaterinburg",
+        "asia/karachi"                    =>   "Karachi",
+        "asia/tashkent"                   =>   "Tashkent",
+        "asia/kolkata"                    =>   "Kolkata",
+        "asia/katmandu"                   =>   "Kathmandu",
+        "asia/dhaka"                      =>   "Dhaka",
+        "asia/colombo"                    =>   "Sri Jayawardenepura",
+        "asia/almaty"                     =>   "Almaty",
+        "asia/novosibirsk"                =>   "Novosibirsk",
+        "asia/rangoon"                    =>   "Rangoon",
+        "asia/bangkok"                    =>   "Bangkok",
+        "asia/jakarta"                    =>   "Jakarta",
+        "asia/krasnoyarsk"                =>   "Krasnoyarsk",
+        "asia/shanghai"                   =>   "Beijing",
+        "asia/chongqing"                  =>   "Chongqing",
+        "asia/hong_kong"                  =>   "Hong Kong",
+        "asia/urumqi"                     =>   "Urumqi",
+        "asia/kuala_lumpur"               =>   "Kuala Lumpur",
+        "asia/singapore"                  =>   "Singapore",
+        "asia/taipei"                     =>   "Taipei",
+        "australia/perth"                 =>   "Perth",
+        "asia/irkutsk"                    =>   "Irkutsk",
+        "asia/ulaanbaatar"                =>   "Ulaan Bataar",
+        "asia/seoul"                      =>   "Seoul",
+        "asia/tokyo"                      =>   "Tokyo",
+        "asia/yakutsk"                    =>   "Yakutsk",
+        "australia/darwin"                =>   "Darwin",
+        "australia/adelaide"              =>   "Adelaide",
+        "australia/melbourne"             =>   "Melbourne",
+        "australia/sydney"                =>   "Sydney",
+        "australia/brisbane"              =>   "Brisbane",
+        "australia/hobart"                =>   "Hobart",
+        "asia/vladivostok"                =>   "Vladivostok",
+        "pacific/guam"                    =>   "Guam",
+        "pacific/port_moresby"            =>   "Port Moresby",
+        "asia/magadan"                    =>   "Magadan",
+        "pacific/noumea"                  =>   "New Caledonia",
+        "pacific/fiji"                    =>   "Fiji",
+        "asia/kamchatka"                  =>   "Kamchatka",
+        "pacific/majuro"                  =>   "Marshall Is.",
+        "pacific/auckland"                =>   "Auckland",
+        "pacific/tongatapu"               =>   "Nuku'alofa"
+      }
+  end
+end

data/lib/forecast/trackable_project.rb

@@ -0,0 +1,38 @@
+# module Harvest
+
+#   # The model for project-tasks combinations that can be added to the timesheet
+#   #
+#   # == Fields
+#   # [+id+] the id of the project
+#   # [+name+] the name of the project
+#   # [+client+] the name of the client of the project
+#   # [+client_id+] the client id of the project
+#   # [+tasks+] trackable tasks for the project
+#   class TrackableProject < Hashie::Mash
+#     include Harvest::Model
+
+#     skip_json_root true
+
+#     def initialize(args = {}, _ = nil)
+#       args       = args.to_hash.stringify_keys
+#       self.tasks = args.delete("tasks") if args["tasks"]
+#       super
+#     end
+
+#     def tasks=(tasks)
+#       self["tasks"] = Task.parse(tasks)
+#     end
+
+#     # The model for trackable tasks
+#     #
+#     # == Fields
+#     # [+id+] the id of the task
+#     # [+name+] the name of the task
+#     # [+billable+] whether the task is billable by default
+#     class Task < Hashie::Mash
+#       include Harvest::Model
+
+#       skip_json_root true
+#     end
+#   end
+# end

data/lib/forecast/user_assignment.rb

@@ -0,0 +1,30 @@
+# module Harvest
+#   class UserAssignment < Hashie::Mash
+#     include Harvest::Model
+
+#     delegate_methods :project_manager? => :is_project_manager
+
+#     def initialize(args = {}, _ = nil)
+#       args = args.to_hash.stringify_keys
+#       self.user    = args.delete("user") if args["user"]
+#       self.project = args.delete("project") if args["project"]
+#       super
+#     end
+
+#     def user=(user)
+#       self["user_id"] = user.to_i
+#     end
+
+#     def project=(project)
+#       self["project_id"] = project.to_i
+#     end
+
+#     def active?
+#       !deactivated
+#     end
+
+#     def user_as_json
+#       {"user" => {"id" => user_id}}
+#     end
+#   end
+# end

data/lib/forecast/version.rb

@@ -0,0 +1,3 @@
+module Forecast
+  VERSION = "0.0.1"
+end

data/lib/forecasted.rb

@@ -0,0 +1,87 @@
+require 'httparty'
+require 'base64'
+require 'delegate'
+require 'hashie'
+require 'json'
+require 'time'
+require 'csv'
+
+require 'ext/array'
+require 'ext/hash'
+require 'ext/date'
+require 'ext/time'
+
+require 'forecast/version'
+require 'forecast/credentials'
+require 'forecast/errors'
+require 'forecast/hardy_client'
+require 'forecast/timezones'
+
+require 'forecast/base'
+
+%w(crud activatable).each {|a| require "forecast/behavior/#{a}"}
+
+%w(model project assignment aggregate).each {|a| require "forecast/#{a}"}
+%w(base projects assignments aggregates).each {|a| require "forecast/api/#{a}"}
+
+module Forecast
+  class << self
+
+    # Creates a standard client that will raise all errors it encounters
+    #
+    # == Options
+    # * Basic Authentication
+    #   * +:subdomain+ - Your HarvestForecast subdomain
+    #   * +:username+ - Your HarvestForecast username
+    #   * +:password+ - Your HarvestForecast password
+    # * OAuth
+    #   * +:access_token+ - An OAuth 2.0 access token
+    #
+    # == Examples
+    #   Forecast.client(subdomain: 'mysubdomain', username: 'myusername', password: 'mypassword')
+    #   Forecast.client(access_token: 'myaccesstoken')
+    #
+    # @return [Forecast::Base]
+    # def client(subdomain: nil, username: nil, password: nil, access_token: nil)
+    def client(ops={})
+      # Forecast::Base.new(subdomain: subdomain, username: username, password: password, access_token: access_token)
+      Forecast::Base.new(ops)
+    end
+
+    # Creates a hardy client that will retry common HTTP errors it encounters and sleep() if it determines it is over your rate limit
+    #
+    # == Options
+    # * Basic Authentication
+    #   * +:subdomain+ - Your HarvestForecast subdomain
+    #   * +:username+ - Your HarvestForecast username
+    #   * +:password+ - Your HarvestForecast password
+    # * OAuth
+    #   * +:access_token+ - An OAuth 2.0 access token
+    #
+    # * +:retry+ - How many times the hardy client should retry errors. Set to +5+ by default.
+    #
+    # == Examples
+    #   Forecast.hardy_client(subdomain: 'mysubdomain', username: 'myusername', password: 'mypassword', retry: 3)
+    #
+    #   Forecast.hardy_client(access_token: 'myaccesstoken', retries: 3)
+    #
+    # == Errors
+    # The hardy client will retry the following errors
+    # * Forecast::Unavailable
+    # * Forecast::InformHarvest
+    # * Net::HTTPError
+    # * Net::HTTPFatalError
+    # * Errno::ECONNRESET
+    #
+    # == Rate Limits
+    # The hardy client will make as many requests as it can until it detects it has gone over the rate limit. Then it will +sleep()+ for the how ever long it takes for the limit to reset. You can find more information about the Rate Limiting at http://www.getforecast.com/api
+    #
+    # @return [Forecast::HardyClient] a Harvest::Base wrapped in a Harvest::HardyClient
+    # @see Forecast::Base
+    # def hardy_client(subdomain: nil, username: nil, password: nil, access_token: nil, retries: 5)
+    def hardy_client(ops={}, retries=5)
+      # Forecast::HardyClient.new(client(subdomain: subdomain, username: username, password: password, access_token: access_token), retries)
+      Forecast::HardyClient.new(client(ops), retries)
+    end
+  end
+end

data/spec/factories.rb

@@ -0,0 +1,17 @@
+FactoryGirl.define do
+  sequence :name do |n|
+    "Joe's Steam Cleaning #{n}"
+  end
+
+  sequence :description do |n|
+    "Item #{n}"
+  end
+
+  sequence :project_name do |n|
+    "Joe's Steam Cleaning Project #{n}"
+  end
+
+  factory :project, class: Forecast::Project do
+    name { generate(:project_name) }
+  end
+end

data/spec/forecast/base_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Forecast::Base do
+  describe "forecast_account_id/access_token errors" do
+    it "should raise error if missing a credential" do
+      expect {
+        Forecast::Base.new({forecast_account_id: 123})
+      }.to raise_error(/must provide/i)
+    end
+  end
+end

data/spec/functional/aggregates_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+describe 'forecast aggregate' do
+
+  describe 'future_scheduled_hours_after' do
+    it 'works' do
+      cassette('aggregate-future_scheduled_hours_after') do
+        x = forecast.aggregates.future_scheduled_hours_after("2016-11-29")
+
+        expect(x.class).to be(Array)
+        expect(x.first.class).to be(Forecast::Aggregate)
+        expect(x.size > 1).to eq(true)
+      end
+    end
+
+    it 'query by project_id' do
+      cassette('aggregate-future_scheduled_hours-query-project_id') do
+        x = forecast.aggregates.future_scheduled_hours_after("2016-11-29", {project_id: mm_forecast_project_id})
+
+        expect(x.class).to be(Array)
+        expect(x.first.class).to be(Forecast::Aggregate)
+
+        expect_belong_to_one_project(x)
+      end
+    end
+  end
+
+  describe 'remaining_budgeted_hours' do
+    it 'works' do
+      cassette('aggregate-remaining_budgeted_hours') do
+        x = forecast.aggregates.remaining_budgeted_hours
+
+        expect(x.class).to be(Array)
+        expect(x.first.class).to be(Forecast::Aggregate)
+
+        expect_belong_to_many_projects(x)
+      end
+    end
+
+    it 'query by (forecast) project_id' do
+      cassette('aggregate-remaining_budgeted_hours') do
+        x = forecast.aggregates.remaining_budgeted_hours({project_id: mm_forecast_project_id})
+
+        expect(x.class).to be(Array)
+        expect(x.first.class).to be(Forecast::Aggregate)
+
+        expect_belong_to_one_project(x)
+      end
+    end
+  end
+
+  def expect_belong_to_one_project(x)
+    project_ids = x.collect(&:project_id)
+    uniq_project_ids = project_ids.uniq
+    expect(uniq_project_ids.size).to eq(1)
+  end
+
+  def expect_belong_to_many_projects(x)
+    project_ids = x.collect(&:project_id)
+    uniq_project_ids = project_ids.uniq
+    expect(uniq_project_ids.size > 1).to eq(true)
+  end
+
+end