neuron-client 0.2.6 → 0.3.0

data/README.md

@@ -11,6 +11,7 @@ Connect to the admin server for read/write access to exposed models:
     config.connection_type = :admin
     config.admin_url = "https://example.com"
     config.admin_key = "secret"
+    config.validate = (ENV['RAILS_ENV'] != 'production')
   end
 
   Short form to copy and paste into console:
@@ -32,8 +33,11 @@ Connect to the Membase (or Memcached) Server for limited read access to some exp
 Create a new API, configure and use it for one specific model:
 
   api = Neuron::Client::API.new
-  api.configure {|config| config.connection_type = :membase; config.membase_servers = '127.0.0.1:11211'}
-  Neuron::Client::Model::Ad.api = api
+  api.configure do |config|
+    config.connection_type = :membase
+    config.membase_servers = '127.0.0.1:11211'
+  end
+  Neuron::Client::Ad.api = api
 
 Zones
 =====
@@ -42,23 +46,22 @@ Zones
 
 Create a zone:
 
-    zone = Neuron::Client::Model::Zone.new(:name => 'test', :response_type => 'Redirect')
+    zone = Neuron::Client::Zone.new(:name => 'test', :response_type => 'Redirect', :redirect_url => 'http://example.com')
     zone.save
 
 ... or simply:
     
-    Neuron::Client::Model::Zone.create(:name => 'test', :response_type => 'Redirect')
+    Neuron::Client::Zone.create(:name => 'test', :response_type => 'Redirect', :redirect_url => 'http://example.com')
 
 List all zones:
 
-    Neuron::Client::Model::Zone.all # => Array of Zone objects (with limited attributes)
+    Neuron::Client::Zone.all # => Array of Zone objects (with limited attributes)
 
 Find a zone by ID:
 
-    Neuron::Client::Model::Zone.find(zone_id)
+    Neuron::Client::Zone.find(zone_id)
 
 Update a zone:
 
-    zone.update_attributes(:parameters => {'foo' => 'bar'})
+    zone.update_attributes(:redirect_url => 'http://example.com/store')
 
-TODO: Finish and finalize the API

data/lib/neuron-client/api.rb

@@ -10,6 +10,7 @@ module Neuron
 
         configure_admin_connection if config.connection_type == :admin
         configure_membase_connection if config.connection_type == :membase
+        @validate = (config.validate != false)
 
         self
       end
@@ -18,6 +19,10 @@ module Neuron
         @config.connection_type
       end
 
+      def validate?
+        @validate != false
+      end
+
       private
 
       def config

data/lib/neuron-client/model/ad.rb

@@ -0,0 +1,142 @@
+module Neuron
+  module Client
+    class Ad
+      include Base
+      include AdCalculations
+
+      ACTIVE_TTL = 60 #seconds
+      PRESSURE_TTL = 60 #seconds
+
+      REDIRECT       = 'Redirect'
+      VIDEO_AD       = 'VideoAd'
+      VAST_NETWORK   = 'VastNetwork'
+      ACUDEO_NETWORK = 'AcudeoNetwork'
+      RESPONSE_TYPES = [REDIRECT, VIDEO_AD, VAST_NETWORK, ACUDEO_NETWORK]
+      
+      SOCIAL_TYPES = %w(facebook googleplus twitter youtube)
+      TIME_ZONES = ActiveSupport::TimeZone.all.collect{|tz| tz.name }
+      FREQUENCY_CAP_WINDOWS = %w(Day Hour)
+      VAST_TRACKER_TYPES = %w(impression clickTracking firstQuartile midpoint thirdQuartile complete)
+
+      ATTRIBUTES = [
+        # Basics
+        :id, # integer
+        :approved, # "Yes" or "No"
+        :daily_cap, # nil, or integer > 1
+        :day_partitions, # nil, or 168 characters of "T" and "F", Sunday first
+        :end_datetime, # nil, or a datetime, in UTC
+        :frequency_cap, # nil, or {"limit" => 1..10, "window" => in Ad::FREQUENCY_CAP_WINDOWS}
+        :geo_target_netacuity_ids, # hash, where keys are in GeoTarget::TYPES, and values are arrays of integer IDs (from NetAcuity)
+        :ideal_impressions_per_hour, # nil, or number > 0
+        :name, # nil, or string with 255 chars or less
+        :overall_cap, # nil, or integer >= 1
+        :pixel_ids, # array of integers
+        :response_type, # a string, in Ad::RESPONSE_TYPES
+        :start_datetime, # a datetime, in UTC
+        :time_zone, # a string, in Ad::TIME_ZONES.
+        :zone_links, # a hash, with zone_ids as keys, and {"priority" => integer, "weight" => number} hashes as values.
+
+        # Timestamps
+        :created_at, :updated_at, # string, datetime in UTC
+
+        # Counts
+        :today_impressed, # nil, or integer >= 0
+        :total_impressed, # nil, or integer >= 0
+
+        # "Redirect" advertisements must have:
+        :redirect_url, # a URI string
+
+        # "VideoAd" advertisements must have:
+        :video_flv_url, # a URI string (no macros)
+        :clickthru_url, # a URI string, perhaps with macros
+        :companion_ad_html, # nil, or a string (raw html, perhaps with macros)
+        :social_urls, # a hash, where keys are in Ad::SOCIAL_TYPES and values are URI strings
+        :vast_tracker_urls, # a hash, where keys are in Ad::VAST_TRACKER_TYPES and values are arrays of URI strings
+
+        # "VastNetwork" advertisements must have:
+        :vast_url, # a URI string, perhaps with macros
+
+        # "AcudeoNetwork" advertisements must have:
+        :acudeo_program_id, # a slug
+      ]
+
+      attr_accessor *ATTRIBUTES
+
+      def attributes
+        ATTRIBUTES
+      end
+
+      STATISTIC_TYPES = %w(selections undeliveries impressions redirects clicks)
+
+      def recent(statistic, by=nil)
+        connected_to_admin!
+        if validate?
+          unless STATISTIC_TYPES.include?(statistic.to_s)
+            raise "Unsupported statistic: #{statistic}"
+          end
+          unless by.nil? || by.to_s == 'zone'
+            raise "Unsupported by: #{by}"
+          end
+        end
+        parameters = by.nil? ? {} : {'by' => by.to_s}
+        connection.get("ads/#{id}/recent/#{statistic}", parameters)
+      end
+
+      def unlink(zone_id)
+        connected_to_admin!
+        validate_uuid!(zone_id)
+        connection.delete("ads/#{id}/zones/#{zone_id}")
+      end
+
+      def total_impressed
+        if connected_to_membase?
+          key = "count_delivery_ad_#{id}"
+          connection.get(key,1).to_f
+        else
+          @total_impressed || 0
+        end
+      end
+
+      def today_impressed
+        if connected_to_membase?
+          now_adjusted_for_ad_time_zone = Time.now.in_time_zone(self.time_zone)
+          formatted_date = now_adjusted_for_ad_time_zone.strftime('%Y%m%d') # format to YYYYMMDD
+          key = "count_delivery_#{formatted_date}_ad_#{id}"
+          connection.get(key,1).to_f
+        else
+          @today_impressed || 0
+        end
+      end
+
+      def active?
+        if connected_to_membase?
+          connection.fetch("Ad:#{id}:active", ACTIVE_TTL) do
+            calculate_active?(Time.now, total_impressed, today_impressed)
+          end
+        else
+          calculate_active?(Time.now, total_impressed, today_impressed)
+        end
+      end
+
+      def pressure
+        if connected_to_membase?
+          connection.fetch("Ad:#{id}:pressure", PRESSURE_TTL) do
+            calculate_pressure(Time.now, total_impressed, today_impressed)
+          end
+        else
+          calculate_pressure(Time.now, total_impressed, today_impressed)
+        end
+      end
+
+      protected
+
+      def to_update_hash(*except)
+        super(:total_impressed, :today_impressed)
+      end
+
+      def to_create_hash(*except)
+        super(:total_impressed, :today_impressed)
+      end
+    end
+  end
+end

data/lib/neuron-client/model/ad_calculations.rb

@@ -0,0 +1,325 @@
+module Neuron
+  module Client
+    module AdCalculations
+      # This module expects the following methods to be defined:
+      # start_datetime (Time, String, or nil)
+      # end_datetime (Time, String, or nil)
+      # time_zone (String)
+      # day_partitions (String, or nil, length = 7*24, matches /^[TF]+$/)
+      # daily_cap (FixNum, or nil)
+      # overall_cap (FixNum, or nil)
+      # ideal_impressions_per_hour (Number, or nil)
+      # total_impressed (Integer, >= 0)
+      # today_impressed (Integer, >= 0)
+
+      def active?
+        calculate_active?(Time.now, total_impressed, today_impressed)
+      end
+
+      def pressure
+        calculate_pressure(Time.now, total_impressed, today_impressed)
+      end
+
+      def calculate_active?(time, total, today)
+        time = time.in_time_zone(time_zone)
+        return false unless within_date_range?(time)
+        return false if partitioned? && !partitioned_hour?(time)
+        !cap_met?(total, today)
+      end
+
+      # Set the optional "active" parameter to true or false if you already know
+      def calculate_pressure(time, total, today, active=nil)
+        return nil if active == false
+        return nil unless active || calculate_active?(time,total,today)
+        time = time.in_time_zone(time_zone)
+        if daily_capped?
+          if daily_cap_precludes_overall_cap?(time,total,today)
+            calculate_overall_pressure(time, total)
+          else
+            calculate_today_pressure(time, today)
+          end
+        elsif overall_pressure_exists?
+          calculate_overall_pressure(time, total)
+        else
+          (ideal_impressions_per_hour || 1.0).to_f
+        end
+      end
+
+      private
+
+      def in_ad_time_zone(time)
+        if time.present?
+          (time.is_a?(String) ? Time.parse(time) : time).in_time_zone(time_zone)
+        end
+      rescue
+        nil
+      end
+
+      def start_in_time_zone
+        in_ad_time_zone(start_datetime)
+      end
+
+      def end_in_time_zone
+        in_ad_time_zone(end_datetime)
+      end
+
+      def daily_capped?
+        !daily_cap.nil? && daily_cap >= 0
+      end
+
+      def overall_capped?
+        !overall_cap.nil? && overall_cap >= 0
+      end
+
+      def overall_pressure_exists?
+        overall_capped? && end_datetime.present?
+      end
+
+      def partitioned?
+        !day_partitions.nil? && day_partitions.length == 24*7 && day_partitions != "T"*24*7
+      end
+
+      def within_date_range?(time)
+        return false if start_datetime.present? && time < start_in_time_zone
+        return false if end_datetime.present? && time >= end_in_time_zone
+        true
+      end
+
+      # Assume time is in the time zone of the ad.
+      # Doesn't worry about whether or not the time is in the ad's date range.
+      # Assumes ad is partitioned.
+      def partitioned_hour?(time)
+        day_partitions.at((time.wday * 24) + time.hour) == 'T'
+      end
+
+      # Assume time is in the time zone of the ad.
+      # Doesn't worry about whether or not the time is in the ad's date range.
+      # Assumes ad is partitioned.
+      # Returns true if there is any active partition the day of the given time.
+      def partitioned_day?(time)
+        day_partitions[(time.wday) * 24, 24].include?('T')
+      end
+
+      # Assumes time is in the time zone of the ad.
+      # Doesn't worry about date range or day partitions.
+      def cap_met?(total_impressed, today_impressed)
+        return true if daily_capped? && (daily_cap <= today_impressed)
+        return true if overall_capped? && (overall_cap <= total_impressed)
+        false
+      end
+
+      # Assumes time is in time_zone of the ad.
+      # Returns true if there's no way we can hit the overall cap
+      #  without busting the daily cap.
+      def daily_cap_precludes_overall_cap?(time,total_impressed,today_impressed)
+        return false unless daily_capped? && overall_capped?
+        return false unless self.end_datetime.present?
+        a = remaining_impressions_via_daily_cap(time, today_impressed)
+        b = remaining_impressions_via_overall_cap(total_impressed)
+        a < b
+      end
+
+      def remaining_impressions_via_overall_cap(total_impressed)
+        [overall_cap - total_impressed, 0].max
+      end
+
+      def remaining_impressions_today(today_impressed)
+        [daily_cap - today_impressed, 0].max
+      end
+
+      def remaining_impressions_via_daily_cap(time, today_impressed)
+        days = remaining_days(time) - 1 # exclude today
+        daily_cap * days + remaining_impressions_today(today_impressed)
+      end
+
+      # Assumes time is in time_zone of the ad.
+      # Assume daily_cap is present.
+      def calculate_today_pressure(time, today_impressed)
+        hours = remaining_hours_today(time)
+        if hours <= 0
+          0.0
+        else
+          impressions = remaining_impressions_today(today_impressed)
+          2 * impressions / hours.to_f
+        end
+      end
+
+      # Assumes time is in time_zone of the ad.
+      # Assume overall_cap is present.
+      # Assume end_datetime is present.
+      def calculate_overall_pressure(time, total_impressed)
+        hours = remaining_hours(time)
+        if hours <= 0
+          0.0
+        else
+          impressions = remaining_impressions_via_overall_cap(total_impressed)
+          impressions / hours.to_f
+        end
+      end
+
+      # remaining_days : the total integer number of days that an ad will run
+      #                  (even for part of the day) between now and the
+      #                  end_datetime.
+      # Assume all dates/times are in the time_zone of the ad.
+      # Assume end_datetime is present.
+      def remaining_days(time)
+        ending = end_in_time_zone
+        beginning = [time, start_in_time_zone].compact.max
+        return 0 unless beginning < ending
+        if partitioned?
+          end_of_beginning_week = beginning_of_week(beginning) + 7.days
+          beginning_of_end_week = beginning_of_week(ending)
+
+          if end_of_beginning_week < beginning_of_end_week
+            head_days = partitioned_days(beginning, end_of_beginning_week)
+            tail_days = partitioned_days(beginning_of_end_week, ending)
+            whole_weeks = (beginning_of_end_week-end_of_beginning_week) / 7.days
+            head_days + (whole_weeks * days_per_week) + tail_days
+          else
+            partitioned_days(beginning, ending)
+          end
+        else
+          (ending.beginning_of_day.to_datetime -
+           beginning.beginning_of_day.to_datetime) + 1
+        end
+      end
+
+      # remaining_hours : the total number of hours that an ad will run from now
+      #                   to the end_datetime, taking day parting into account.
+      # Assume all dates/times are in the time_zone of the ad.
+      def remaining_hours(time)
+        ending = end_in_time_zone
+        beginning = [time, start_in_time_zone].compact.max
+        return 0 unless beginning < ending
+        if partitioned?
+
+          end_of_beginning_week = beginning_of_week(beginning) + 7.days
+          beginning_of_end_week = beginning_of_week(ending)
+
+          if end_of_beginning_week < beginning_of_end_week
+            head_hours = partitioned_hours(beginning, end_of_beginning_week)
+            tail_hours = partitioned_hours(beginning_of_end_week, ending)
+            whole_weeks = (beginning_of_end_week-end_of_beginning_week) / 7.days
+            head_hours + (whole_weeks * hours_per_week) + tail_hours
+          else
+            partitioned_hours(beginning, ending)
+          end
+        else
+          actual_hours(beginning, ending)
+        end
+      end
+
+      # remaining_hours_today : the total number of hours that an ad will run
+      #                         between now and the end of the day, taking day
+      #                         parting into account.
+      # Assume all dates/times are in the time_zone of the ad.
+      def remaining_hours_today(time)
+        beginning = [time, start_in_time_zone].compact.max
+        ending = [time.beginning_of_day + 1.day, end_in_time_zone].compact.min
+        return 0 unless beginning < ending
+        if partitioned?
+          partitioned_hours(beginning, ending)
+        else
+          actual_hours(beginning, ending)
+        end
+      end
+
+      # Assume time is in the time_zone of the ad.
+      # Assume a week begins on Sunday.
+      def beginning_of_week(time)
+        recent_monday = time.monday
+        sunday_before_recent_monday = recent_monday - 1.day
+        if (time - sunday_before_recent_monday) < 7.days
+          sunday_before_recent_monday
+        else
+          sunday_before_recent_monday + 7.days
+        end
+      end
+
+      def beginning_of_hour(time)
+        time.change(:min => 0, :sec => 0, :usec => 0)
+      end
+
+      # Assume beginning and ending are in the ad's time_zone.
+      # Assume beginning and ending are within the ad's date range.
+      # Assume ad is partitioned.
+      def partitioned_hours(beginning, ending)
+        return 0 unless beginning < ending
+        total = 0.0
+        this_hour = beginning_of_hour(beginning)
+        last_hour = beginning_of_hour(ending)
+        if this_hour.to_i == last_hour.to_i
+          if partitioned_hour?(this_hour)
+            total = actual_hours(beginning, ending)
+          end
+        else
+          next_hour = this_hour + 1.hour
+          if partitioned_hour?(this_hour)
+            total += actual_hours(beginning, next_hour)
+          end
+          each_hour(next_hour, last_hour) do |hour|
+            total += 1 if partitioned_hour?(hour)
+          end
+          if partitioned_hour?(last_hour)
+            total += actual_hours(last_hour, ending)
+          end
+        end
+        total
+      end
+
+      # Assume beginning and ending are in the ad's time_zone.
+      # Assume beginning and ending are within the ad's date range.
+      # Assume ad is partitioned.
+      # Assume beginning and ending are within a week of each other.
+      # Computes integer number of days where any part of the day is active.
+      def partitioned_days(beginning, ending)
+        return 0 unless beginning < ending
+
+        end_of_beginning_day = beginning.beginning_of_day + 1.day
+        beginning_of_end_day = ending.beginning_of_day
+
+        if end_of_beginning_day < beginning_of_end_day
+          days = 0
+          days += 1 if partitioned_hours(beginning, end_of_beginning_day) > 0
+          days += 1 if partitioned_hours(beginning_of_end_day, ending) > 0
+          each_day(end_of_beginning_day, beginning_of_end_day) do |day|
+            days += 1 if partitioned_day?(day)
+          end
+          days
+        else
+          (partitioned_hours(beginning,ending) > 0) ? 1 : 0
+        end
+      end
+
+      def each_day(beginning, ending)
+        time = beginning.clone
+        while (time < ending)
+          yield time
+          time += 1.day
+        end
+      end
+
+      def each_hour(beginning, ending)
+        time = beginning.clone
+        while(time < ending)
+          yield time
+          time += 1.hour
+        end
+      end
+
+      def actual_hours(beginning, ending)
+        (ending.to_f - beginning.to_f) / 3600
+      end
+
+      # Assumes ad is partitioned.
+      def days_per_week
+        (0..6).map{|d| day_partitions[d*24,24].include?('T') ? 1 : 0 }.sum
+      end
+
+      # Assumes ad is partitioned.
+      def hours_per_week
+        day_partitions.count("T")
+      end
+    end
+  end
+end

data/lib/neuron-client/model/ad_zone.rb

@@ -0,0 +1,45 @@
+module Neuron
+  module Client
+    class AdZone
+      include Base
+
+      ATTRIBUTES = [
+        :ad_id, # integer
+        :zone_id, # string, UUID
+        :weight, # number
+        :priority, # integer, 1..10
+
+        :created_at, #string, datetime in UTC
+        :updated_at, #string, datetime in UTC
+      ]
+
+      attr_accessor *ATTRIBUTES
+
+      def attributes
+        ATTRIBUTES
+      end
+
+      def new_record?
+        true
+      end
+
+      def id
+        nil
+      end
+
+      def destroy
+        connected_to_admin!
+        validate_id!(ad_id)
+        validate_uuid!(zone_id)
+        connection.delete("zones/#{zone_id}/ads/#{ad_id}")
+      end
+      
+      def self.unlink(ad_id, zone_id)
+        connected_to_admin!
+        validate_id!(ad_id)
+        validate_uuid!(zone_id)
+        connection.delete("zones/#{zone_id}/ads/#{ad_id}")
+      end
+    end
+  end
+end