adapi 0.0.2 → 0.0.3

data/lib/adapi/ad_group_criterion.rb

@@ -1,67 +1,25 @@
 module Adapi
-  class AdGroupCriterion < Api
-
-    def initialize(params = {})
-      params[:service_name] = :AdGroupCriterionService
-      super(params)
-    end
-
-    def self.create(params = {})
-      ad_group_criterion_service = AdGroupCriterion.new
-
-      raise "No criteria available" unless params[:criteria].is_a?(Array)
-
-      # if ad_group_id is supplied as separate parameter, include it into
-      # criteria
-      if params[:ad_group_id]
-        params[:criteria].map! { |c| c.merge(:ad_group_id => params[:ad_group_id].to_i) }
-      end
 
-      operation = params[:criteria].map do |criterion|
-        { :operator => 'ADD', :operand => criterion }
-      end
-    
-      response = ad_group_criterion_service.service.mutate(operation)
+  # http://code.google.com/apis/adwords/docs/reference/latest/AdGroupCriterionService.html
+  #
+  class AdGroupCriterion < Api
 
-      ad_group_criteria = nil
-      if response and response[:value]
-        ad_group_criteria = response[:value]
-        puts "Added #{ad_group_criteria.length} criteria " # "to ad group #{ad_group_id}."
-        ad_group_criteria.each do |ad_group_criterion|
-          puts "  Criterion id is #{ad_group_criterion[:criterion][:id]} and " +
-            "type is #{ad_group_criterion[:criterion][:"@xsi:type"]}."
-        end
-      else
-        puts "No criteria were added."
-      end
+    attr_accessor :ad_group_id, :criterion_use
 
-      ad_group_criteria 
+    def attributes
+      super.merge('ad_group_id' => ad_group_id)
     end
 
-    def find(params = {})
-      raise "No Campaign ID" unless params[:campaign_id]
-      campaign_id = params[:campaign_id]
-
-      selector = {
-        :fields => ['Id', 'Name'],
-        # :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
-        :predicates => [{
-          :field => 'CampaignId', :operator => 'EQUALS', :values => campaign_id
-        }]
-      }
+    def initialize(params = {})
+      params[:service_name] = :AdGroupCriterionService
 
-      response = @service.get(selector)
+      @xsi_type = 'AdGroupCriterion'
 
-      if response and response[:entries]
-        ad_groups = response[:entries]
-        puts "Campaign ##{campaign_id} has #{ad_groups.length} ad group(s)."
-        ad_groups.each do |ad_group|
-          puts "  Ad group name is \"#{ad_group[:name]}\" and id is #{ad_group[:id]}."
-        end
-     else
-       puts "No ad groups found for campaign ##{campaign_id}."
-     end
+      %w{ ad_group_id criterion_use }.each do |param_name|
+        self.send "#{param_name}=", params[param_name.to_sym]
+      end
 
+      super(params)
     end
 
   end

data/lib/adapi/api.rb

@@ -1,9 +1,21 @@
 module Adapi
   class Api
+    extend ActiveModel::Naming
+    include ActiveModel::Validations
+    include ActiveModel::Serialization
+    include ActiveModel::Conversion
+    # TODO include ActiveModel::Dirty
 
-    attr_accessor :adwords, :service, :version, :params
+    attr_accessor :adwords, :service, :version, :params,
+      :id, :status, :xsi_type
+
+    def attributes
+      { 'status' => status, 'xsi_type' => xsi_type }
+    end
 
     def initialize(params = {})
+      params.symbolize_keys!
+
       raise "Missing Service Name" unless params[:service_name]
 
       puts "\n\nEXISTING INSTANCE USED\n\n" if params[:adwords_api_instance]
@@ -16,5 +28,99 @@ module Adapi
       @params = params
     end
 
+    def persisted?
+      false
+    end
+
+    # FIXME hotfix, should be able to sort it out better through ActiveModel
+    def [](k)
+      self.send(k)
+    end
+
+    def []=(k,v)
+      self.send("#{k}=", v)
+    end
+
+    # return parameters in hash
+    # filtered for API calls by default: without :id and :status parameters
+    # PS: attributes method always returns all specified attributes
+    #
+    def data(filtered = true)
+      data_hash = self.serializable_hash.symbolize_keys
+      
+      if filtered
+        data_hash.delete(:id)
+        data_hash.delete(:status)
+      end
+      
+      data_hash
+    end
+
+    # alias to instance method: data
+    # 
+    alias :to_hash :data
+
+    # detects whether the instance has been saved already
+    #
+    def new?
+      self.id.blank?
+    end
+
+    def self.create(params = {})
+      api_instance = self.new(params)
+      api_instance.create
+      api_instance
+    end
+
+    # done mostly for campaign, probably won't work pretty much anywhere else
+    # which can be easily fixed creating by self.update method for specific
+    # class
+    #
+    def self.update(params = {})
+      # PS: updating campaign without finding it is much faster
+      api_instance = self.new()
+      api_instance.id = params.delete(:id)
+      api_instance.errors.add('id', 'is missing') unless api_instance.id
+      
+      api_instance.update(params)
+      api_instance
+    end
+
+
+    # wrap AdWords add/update/destroy actions and deals with errors
+    # PS: Keyword and Ad models have their own wrappers because of
+    # PolicyViolations
+    #
+    def mutate(operation)      
+      operation = [operation] unless operation.is_a?(Array)
+      
+      # fix to save space during specifyng operations
+      operation = operation.map do |op|
+        op[:operand].delete(:status) if op[:operand][:status].nil?
+        op
+      end
+      
+      begin    
+        response = @service.mutate(operation)
+    
+      rescue AdsCommon::Errors::HttpError => e
+        self.errors.add(:base, e.message)
+
+      # traps any exceptions raised by AdWords API
+      rescue AdwordsApi::Errors::ApiException => e
+        error_key = "[#{self.xsi_type.underscore}]"
+  
+        self.errors.add(error_key, e.message)
+      end
+      
+      response
+    end
+
+    # convert number to micro units (unit * one million)
+    #
+    def self.to_micro_units(x)
+      (x.to_f * 1e6).to_i
+    end
+
   end
 end

data/lib/adapi/campaign.rb

@@ -1,141 +1,191 @@
 module Adapi
   class Campaign < Api
 
+    # http://code.google.com/apis/adwords/docs/reference/latest/CampaignService.Campaign.html
+    #
+    attr_accessor :name, :serving_status, :start_date, :end_date, :budget,
+      :bidding_strategy, :network_setting, :targets, :ad_groups
+
+    def attributes
+      super.merge('name' => name, 'start_date' => start_date, 'end_date' => end_date,
+        'budget' => budget, 'bidding_strategy' => bidding_strategy,
+        'network_setting' => network_setting, 'targets' => targets,
+        'ad_groups' => ad_groups)
+    end
+
+    validates_presence_of :name, :status
+    validates_inclusion_of :status, :in => %w{ ACTIVE DELETED PAUSED }
+
     def initialize(params = {})
       params[:service_name] = :CampaignService
-      super(params)
-   end
+      
+      @xsi_type = 'Campaign'
 
-    # campaign data can be passed either as single hash:
-    # Campaign.create(:name => 'Campaign 123', :status => 'ENABLED')
-    # or as hash in a :data key:
-    # Campaign.create(:data => { :name => 'Campaign 123', :status => 'ENABLED' })
-    #
-    def self.create(params = {})
-      campaign_service = Campaign.new
+      %w{ name status start_date end_date budget bidding_strategy
+      network_setting targets ad_groups}.each do |param_name|
+        self.send "#{param_name}=", params[param_name.to_sym]
+      end
 
-      # give users options to shorten input params
-      params = { :data => params } unless params.has_key?(:data)
+      # convert bidding_strategy to GoogleApi
+      # can be either string (just xsi_type) or hash (xsi_type with params)
+      # TODO validations for xsi_type
+      # 
+      unless @bidding_strategy.is_a?(Hash)
+        @bidding_strategy = { :xsi_type => @bidding_strategy }
+      end
 
-      # prepare for adding campaign
-      ad_groups = params[:data].delete(:ad_groups).to_a
-      targets = params[:data].delete(:targets)
-      
-      operation = { :operator => 'ADD', :operand => params[:data] }
-    
-      response = campaign_service.service.mutate([operation])
-
-      campaign = nil
-      if response and response[:value]
-        campaign = response[:value].first
-        puts "Campaign with name '%s' and ID %d was added." % [campaign[:name], campaign[:id]]
-      else
-        return nil
+      if @bidding_strategy[:bid_ceiling]
+        @bidding_strategy[:bid_ceiling] = {
+          :micro_amount => Api.to_micro_units(@bidding_strategy[:bid_ceiling])
+        }
       end
 
+      # convert budget to GoogleApi
+      # TODO validations for budget
+      #
+      # budget can be integer (amount) or hash
+      @budget = { :amount => @budget } unless @budget.is_a?(Hash)
+      @budget[:period] ||= 'DAILY'
+      @budget[:amount] = { :micro_amount => Api.to_micro_units(@budget[:amount]) }
+      # PS: not sure if this should be a default. maybe we don't even need it
+      @budget[:delivery_method] ||= 'STANDARD'
+
+      @targets ||= []
+      @ad_groups ||= []
+
+      super(params)
+    end
+
+    # create campaign with ad_groups and ads
+    #
+    def create
+      return false unless self.valid?      
+      
+      operand = Hash[
+        [ :name, :status, :start_date, :end_date,
+          :budget, :bidding_strategy, :network_setting ].map do |k|
+          [ k.to_sym, self.send(k) ] if self.send(k)
+        end.compact
+      ]
+
+      response = self.mutate(
+        :operator => 'ADD', 
+        :operand => operand
+      )
+      
+      return false unless (response and response[:value])
+      
+      self.id = response[:value].first[:id] rescue nil
+      
       # create targets if they are available
-      if targets
-        Adapi::CampaignTarget.create(
-          :campaign_id => campaign[:id],
-          :targets => targets,
-          :api_adwords_instance => campaign_service.adwords
+      if targets.size > 0
+        target = Adapi::CampaignTarget.create(
+          :campaign_id => @id,
+          :targets => targets
         )
+        
+        if (target.errors.size > 0)
+          self.errors.add("[campaign target]", target.errors.to_a)
+          self.rollback
+          return false 
+        end
       end
 
-      # if campaign has ad_groups, create them as well
       ad_groups.each do |ad_group_data|
-        Adapi::AdGroup.create(
-          :data => ad_group_data.merge(:campaign_id => campaign[:id]),
-          :api_adwords_instance => campaign_service.adwords
+        ad_group = Adapi::AdGroup.create(
+          ad_group_data.merge(:campaign_id => @id)
         )
+
+        if (ad_group.errors.size > 0)
+          self.errors.add("[ad group] \"#{ad_group.name}\"", ad_group.errors.to_a)
+          self.rollback
+          return false 
+        end
       end
 
-      campaign
+      return true
     end
 
     # general method for changing campaign data
     # TODO enable updating of all campaign parts at once, same as for Campaign#create method
+    #
+    # TODO implement class method
     # 
-    def self.update(params = {})
-      campaign_service = Campaign.new
+    def update(params = {})
+      # TODO validation or refuse to update
 
-      # give users options to shorten input params
-      params = { :data => params } unless params.has_key?(:data)
+      response = self.mutate(
+        :operator => 'SET', 
+        :operand => params.merge(:id => @id)
+      )
 
-      campaign_id = params[:id] || params[:data][:id] || nil
-      return nil unless campaign_id
-      
-      operation = { :operator => 'SET',
-        :operand => params[:data].merge(:id => campaign_id.to_i)
-      }
-    
-      response = campaign_service.service.mutate([operation])
-
-      if response and response[:value]
-        campaign = response[:value].first
-        puts 'Campaign id %d successfully updated.' % campaign[:id]
-      else
-        puts 'No campaigns were updated.'
-      end
+      return false unless (response and response[:value])
+
+      # faster than self.find
+      params.each_pair { |k,v| self.send("#{k}=", v) }
 
-      return campaign
+      true      
     end
 
-    def self.set_status(params = {})
-      params[:id] ||= (params[:data] || params[:data][:id]) || nil
-      return nil unless params[:id]
-      return nil unless %w{ ACTIVE PAUSED DELETED }.include?(params[:status])
+    def activate; update(:status => 'ACTIVE'); end
+    def pause; update(:status => 'PAUSED'); end
+    def delete; update(:status => 'DELETED'); end
 
-      self.update(:id => params[:id], :status => params[:status])
-    end
+    def rename(new_name); update(:name => new_name); end
 
-    def self.activate(params = {})
-      self.set_status params.merge(:status => 'ACTIVE')
-    end
+    # when Campaign#create fails, "delete" campaign
+    def rollback
+      if (@status == 'DELETED')
+        self.errors.add(:base, 'Campaign is already deleted.')
+        return false
+      end
 
-    def self.pause(params = {})
-      self.set_status params.merge(:status => 'PAUSED')
+      update(
+        :name => "#{@name}_DELETED_#{(Time.now.to_f * 1000).to_i}",
+        :status => 'DELETED'
+      )
     end
 
-    def self.delete(params = {})
-      self.set_status params.merge(:status => 'DELETED')
+    def find # == refresh
+      Campaign.find(:first, :id => @id)
     end
 
-    def self.rename(params = {})
-      params[:id] ||= (params[:data] || params[:data][:id]) || nil
-      return nil unless (params[:id] && params[:name])
+    def self.find(amount = :all, params = {})
+      params.symbolize_keys!
+      first_only = (amount.to_sym == :first)
 
-      self.update(:id => params[:id], :name => params[:name])
-    end
+      raise "Campaign ID (:id param) is required" unless params[:id]
 
-    def self.find(params = {})
-      campaign_service = Campaign.new
+      predicates = [ :id ].map do |param_name|
+        if params[param_name]
+          {:field => param_name.to_s.camelcase, :operator => 'EQUALS', :values => params[param_name] }
+        end
+      end.compact
 
+      # TODO display the rest of the data
+      # TODO get NetworkSetting - setting as in fields doesn't work
       selector = {
-        :fields => ['Id', 'Name', 'Status']
-        # :predicates => [{ :field => 'Id', :operator => 'EQUALS', :values => '334315' }]
-        # :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}]
+        :fields => ['Id', 'Name', 'Status', 'BiddingStrategy' ],
+        :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
+        :predicates => predicates
       }
 
-      # set filtering conditions: find by id, status etc.
-      if params[:conditions]
-        selector[:predicates] = params[:conditions].map do |c|
-          { :field => c[0].to_s.capitalize, :operator => 'EQUALS', :values => c[1] }
-        end
-      end
+      response = Campaign.new.service.get(selector)
 
-      response = campaign_service.service.get(selector)
+      response = (response and response[:entries]) ? response[:entries] : []
 
-      return (response and response[:entries]) ? response[:entries].to_a : []
-    
-      if response
-        response[:entries].to_a.each do |campaign|
-          puts "Campaign name is \"#{campaign[:name]}\", id is #{campaign[:id]} " +
-              "and status is \"#{campaign[:status]}\"."
-        end
-      else
-        puts "No campaigns were found."
+      response.map! do |campaign_data|
+        campaign = Campaign.new(campaign_data)
+        # TODO allow mass assignment of :id
+        campaign.id = campaign_data[:id]
+        campaign
       end
+
+      first_only ? response.first : response
+    end
+
+    def find_ad_groups(first_only = true)
+      AdGroup.find( (first_only ? :first : :all), :campaign_id => self.id )
     end
 
   end