zuck 0.0.4

data/lib/zuck/facebook/targeting_spec.rb

@@ -0,0 +1,200 @@
+module Zuck
+
+  # Thrown when a keyword, country, gender etc. is not valid
+  class InvalidSpecError    < RuntimeError; end
+  class InvalidKeywordError < InvalidSpecError; end
+  class InvalidCountryError < InvalidSpecError; end
+  class InvalidGenderError  < InvalidSpecError; end
+  class ParamsMissingError  < InvalidSpecError; end
+
+
+
+  #
+  # Some helpers around https://developers.facebook.com/docs/reference/ads-api/targeting-specs/
+  # Use like this:
+  #
+  #     > ts = Facebook::TargetingSpec.new(graph, ad_account, keyword: 'foo', countries: ['US'])
+  #     > ts.spec
+  #     => {
+  #        :countries => [
+  #          [0] "US"
+  #        ],
+  #         :keywords => [
+  #          [0] "foo"
+  #        ]
+  #     }
+  #     > ts.fetch_reach
+  #     => 12345
+  #
+  class TargetingSpec
+    attr_reader :spec, :graph
+
+    # @param graph [Koala::Facebook::API] The koala graph object to use
+    # @param ad_account [String] The ad account you want to use to query the facebook api
+    # @param spec [Hash] The targeting spec. Supported keys:
+    #
+    #   - `:countries`: Array of uppercase two letter country codes
+    #   - `:genders` (optional): Can be an array with 2 (female) and 1 (male)
+    #   - `:gender` (optional): Set it to 'male' or 'female' to autoconfigure the genders array
+    #   - `:age_min` (optional): In years
+    #   - `:age_max` (optional): In years
+    #   - `:age_class` (optional): Set it to `young` or `old` to autoconfigure `age_min` and `age_max`
+    #     for people older or younger than 25
+    #   - `:locales` (optional): [disabled] Array of integers, valid keys are here https://graph.facebook.com/search?type=adlocale&q=en
+    #   - `:keywords`: Array of strings with keywords
+    #
+    def initialize(graph, ad_account, spec = nil)
+      @validated_keywords = {}
+      @graph = graph
+      @ad_account = "act_#{ad_account}".gsub('act_act_', 'act_')
+      self.spec = spec
+    end
+
+    # @param spec [Hash] See {#initialize}
+    def spec=(spec)
+      @spec = spec || {}
+      build_spec
+    end
+
+    # @return [Hash] The reach for the options given in {#initialize}, see 
+    #   https://developers.facebook.com/docs/reference/ads-api/reachestimate/
+    def fetch_reach
+      validate_spec
+      json = @spec.to_json
+      o = "#{@ad_account}/reachestimate"
+      result = graph.get_object(o, targeting_spec: json)
+      return false unless result
+      result.with_indifferent_access
+    end
+
+    def validate_keywords
+      @spec[:keywords].each do |w|
+        raise(InvalidKeywordError, w) unless validate_keyword(w)
+      end
+    end
+
+    # Validates a single keyword from the cache or calls
+    # {TargetingSpec.validate_keywords}.to validate the keywords via
+    # facebook's api.
+    # @param keyword [String] A single keyword (will be downcased)
+    # @return boolean
+    def validate_keyword(keyword)
+      if @validated_keywords[keyword] == nil
+        keywords = normalize_array([@spec[:keywords]] + [keyword])
+        @validated_keywords = self.class.validate_keywords(@graph, keywords)
+      end
+      @validated_keywords[keyword] == true
+    end
+
+    # Checks the ad api to see if the given keywords are valid
+    # @return [Hash] The keys are the (lowercased) keywords and the values their validity
+    def self.validate_keywords(graph, keywords)
+      keywords = normalize_array(keywords).map{|k| k.gsub(',', '%2C')}
+      search = graph.search(nil, type: 'adkeywordvalid', keyword_list: keywords.join(","))
+      results = {}
+      search.each do |r|
+        results[r['name'].downcase] = r['valid']
+      end
+      results
+    end
+
+    # Fetches a bunch of reach estimates from facebook at once.
+    # @param graph Koala graph instance
+    # @param specs [Array<Hash>] An array of specs as you would pass to {#initialize}
+    # @return [Array<Hash>] Each spec you passed in as the requests parameter with
+    #   the [:success] set to true/false and [:reach]/[:error] are filled respectively
+    def self.batch_reaches(graph, ad_account, specs)
+
+      # Make all requests
+      reaches = []
+      specs.each_slice(50) do |specs_slice|
+        reaches += graph.batch do |batch_api|
+          specs_slice.each do |spec|
+            targeting_spec = Zuck::TargetingSpec.new(batch_api, ad_account, spec)
+            targeting_spec.fetch_reach
+          end
+        end
+      end
+
+      # Structure results
+      result = []
+      reaches.each_with_index do |res, i|
+        result[i] = specs[i].dup
+        if res.class < StandardError
+          result[i][:success] = false
+          result[i][:error]   = res
+        else
+          result[i][:success] = true
+          result[i][:reach]   = res.with_indifferent_access
+        end
+      end
+      result
+    end
+
+    # Convenience method, parameters are the same as in {#initialize}
+    # @return (see #initialize)
+    def self.fetch_reach(graph, ad_account, options)
+      ts = Zuck::TargetingSpec.new(graph, ad_account, options)
+      ts.fetch_reach
+    end
+
+    private
+
+    def self.normalize_array(arr)
+      [arr].flatten.compact.map(&:to_s).map(&:downcase).uniq.sort
+    end
+
+    def self.normalize_countries(countries)
+      normalize_array(countries).map(&:upcase)
+    end
+
+    def normalize_array(arr)
+      self.class.normalize_array(arr)
+    end
+
+    def normalize_countries(countries)
+      self.class.normalize_countries(countries)
+    end
+
+    def validate_spec
+      @spec[:countries]   = normalize_countries(@spec[:countries])
+      @spec[:keywords]    = normalize_array(@spec[:keywords])
+      @spec[:broad_age] ||= false
+      raise(InvalidCountryError, "Need to set :countries") unless @spec[:countries].present?
+      unless @spec[:keywords].present? or @spec[:connections].present?
+        raise(ParamsMissingError, "Need to set :keywords or :connections")
+      end
+    end
+
+    def build_spec
+      return unless @spec
+      age = @spec.delete(:age_class)
+      if age.to_s == 'young'
+        @spec[:age_min] = 13
+        @spec[:age_max] = 24
+      elsif age.to_s == 'old'
+        @spec[:age_min] = 25
+      else
+        @spec[:age_min] = 13
+      end
+
+      gender = spec.delete(:gender)
+      if gender and !['male', 'female'].include?(gender.to_s)
+        raise(InvalidGenderError, "Gender can only be male or female")
+      end
+      @spec[:genders] = [1] if gender.to_s == 'male'
+      @spec[:genders] = [2] if gender.to_s == 'female'
+
+      keyword = spec.delete(:keyword)
+      @spec[:keywords] = normalize_array([keyword, @spec[:keywords]])
+
+      country = spec.delete(:country)
+      @spec[:countries] = normalize_countries([country, @spec[:countries]])
+
+      connections = spec.delete(:connections)
+      @spec[:connections] = normalize_array([connections, @spec[:connections]])
+
+    end
+
+  end
+end

data/lib/zuck/fb_object/dsl.rb

@@ -0,0 +1,110 @@
+require_relative 'error'
+
+module Zuck
+ module FbObject
+   module DSL
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # @return [String] Most facebook objects will need to return their
+    #   id property here, so that's the default. Overwrite if necessary
+    def path
+      self[:id] or raise "Can't find a path unless I have an id #{self.inspect}"
+    end
+
+    module ClassMethods
+
+      # Don't allow create/update/delete
+      def read_only
+        @read_only = true
+      end
+
+      def read_only?
+        !!@read_only
+      end
+
+      # Part of our little DSL, sets the part of the path that fetches the
+      # list of objects from facebook.
+      #
+      #     class Foo < FbObject
+      #        ...
+      #        list_path :foos
+      #      end
+      #
+      # {FbObject} uses this to construct a path together with this class'
+      # parent object's path method (which is usually just it's ID
+      # property)
+      #
+      # @param path [String, Symbol] Pass a value if you want to set the
+      #   list_path for this object.
+      # @return The object's `list_path`
+      def list_path(path = nil)
+        @list_path = path if path
+        @list_path
+      end
+
+      # Pretty much like a `belongs_to`, but is used to construct paths to
+      # access the facebook api.
+      #
+      # It also defines a getter method. Look
+      #
+      #     class AdCampaign < FbObject
+      #       ...
+      #       parent_object :ad_account
+      #     end
+      #
+      # Now on instances you can call `my_campaign.ad_account` to fetch
+      # the ad account your campaign is part of.
+      #
+      # @param type [Symbol] Pass an underscored symbol here, for example
+      #   `ad_account`
+      def parent_object(type)
+        @parent_object_type = type.to_s
+        define_method(type) do
+          @parent_object
+        end
+      end
+
+      # Defines which other classes might have this one as their parent.
+      #
+      # If you do something like
+      #
+      # ```ruby
+      # class Foo < RawFbObject
+      #   ...
+      #   connections :dings, :dongs
+      # end
+      # ```
+      #
+      # then your `Foo` instances will have a `#dings` and `#dongs` methods,
+      # which will call `Ding.all` and `Dong.call` on the appropriate graph
+      # object.
+      #
+      # Also, you will get a `#create_ding` and `#create_dong` methods that
+      # forward to `Ding.new` and `Dong.new`.
+      def connections(*args)
+        args.each do |c|
+
+          # Why a lambda? Because it gets evaluated on runtime, not now. This is a
+          # good thing because it allows for randomly loading files with classes
+          # that inherit from FbObject.
+          class_resolver = lambda{"Zuck::#{c.to_s.singularize.camelize}".constantize}
+
+          # Define getter for connections
+          define_method(c.to_s.pluralize) do
+            class_resolver.call.all(graph, self)
+          end
+
+          # Define create method for connections
+          define_method("create_#{c.to_s.singularize}") do |data|
+            class_resolver.call.create(graph, data, self)
+          end
+        end
+      end
+    end
+   end
+ end
+end
+

data/lib/zuck/fb_object/error.rb

@@ -0,0 +1,8 @@
+module Zuck
+  class ZuckError < StandardError; end
+  module Error
+
+    class ReadOnly < ::Zuck::ZuckError; end
+
+  end
+end

data/lib/zuck/fb_object/hash_delegator.rb

@@ -0,0 +1,111 @@
+module Zuck
+
+  # Including this module does three things:
+  #
+  # 1.  Lets you use `x[:foo]` to access keys of the
+  #     underlying Hash
+  # 2.  Lets you use `x[:foo] = :bar` to set values in
+  #     the underlying Hash
+  # 3.  Lets you define which keys are to be expected in
+  #     the underlying hash. These keys will become methods
+  #
+  # Here's an example:
+  #
+  #     class MyObjectWithHash
+  #
+  #       include Zuck::HashDelegator
+  #
+  #       known_keys :foo, :bar
+  #
+  #       def initialize(initial_data)
+  #         set_data(initial_data)
+  #       end
+  #     end
+  #
+  #     > x = MyObjectWithHash.new(foo: :foo)
+  #     > x.foo
+  #     => :foo
+  #     > x.bar
+  #     => nil
+  #     > x['bar'] = :everything_is_a_symbol
+  #     > x[:bar]
+  #     => :everything_is_a_symbol
+  #     > x['bar']
+  #     => :everything_is_a_symbol
+  #     > x.foo
+  #     => :everything_is_a_symbol
+  #     > x.foo = :you_also_have_setters
+  #     => :you_also_have_setters
+  #
+  # As you can see, all string keys become symbols and the
+  # foo and bar methods were added because they are known keys
+  #
+  module HashDelegator
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def known_keys(*args)
+        args.each do |key|
+
+          # Define getter
+          self.send(:define_method, key) do
+            init_hash
+            @hash_delegator_hash[key]
+          end
+
+          # Define setter
+          self.send(:define_method, "#{key}=") do |val|
+            init_hash
+            @hash_delegator_hash[key] = val
+          end
+        end
+      end
+    end
+
+    def set_data(d)
+      e = "You can only assign a Hash to #{self.class}, not a #{d.class}"
+      raise e unless d.is_a? Hash
+      hash = Hash.new
+      d.each do |key, value|
+        hash[(key.to_sym rescue key) || key] = value
+      end
+      @hash_delegator_hash = hash
+    end
+
+    def data=(d)
+      set_data(d)
+    end
+
+    def data
+      @hash_delegator_hash
+    end
+
+    def [](key)
+      init_hash
+      @hash_delegator_hash[key.to_sym]
+    end
+
+    def []=(key, value)
+      init_hash
+      @hash_delegator_hash[key.to_sym] = value
+    end
+
+    def to_s
+      init_hash
+      vars = @hash_delegator_hash.map do |k, v|
+        "#{k}: #{v.to_json}"
+      end.join(", ")
+      "#<#{self.class} #{vars}>"
+    end
+
+    private
+
+    def init_hash
+      @hash_delegator_hash ||= {}
+    end
+
+  end
+end

data/lib/zuck/fb_object/helpers.rb

@@ -0,0 +1,57 @@
+module Zuck
+  module FbObject
+    module Helpers
+
+      private
+
+      def get(graph, path)
+        begin
+          graph.get_object(path)
+        rescue => e
+          puts "#{e} graph.get_object(#{path.to_json})" if in_irb?
+          raise e
+        end
+      end
+
+      def create_connection(graph, parent, connection, args = {}, opts = {})
+        begin
+          graph.put_connections(parent, connection, args, opts)
+        rescue => e
+          msg = "#{e} graph.put_connections(#{parent.to_json}, #{connection.to_json}, #{args.to_json}, #{opts.to_json})"
+          puts msg if in_irb?
+          raise e
+        end
+      end
+
+      def post(graph, path, data, opts = {})
+        begin
+          graph.graph_call(path.to_s, data, "post", opts)
+        rescue => e
+          msg = "#{e} graph.graph_call(#{path.to_json}, #{data.to_json}, \"post\", #{opts.to_json})"
+          puts msg if in_irb?
+          raise e
+        end
+      end
+
+      def delete(graph, path)
+        begin
+          graph.delete_object(path)
+        rescue => e
+          puts "#{e} graph.delete(#{path.to_json})" if in_irb?
+          raise e
+        end
+      end
+
+      def path_with_parent(parent=nil)
+        paths = []
+        paths << parent.path if parent
+        paths << list_path
+        paths.join('/')
+      end
+
+      def in_irb?
+        defined?(IRB)
+      end
+    end
+  end
+end

data/lib/zuck/fb_object/read.rb

@@ -0,0 +1,147 @@
+module Zuck
+ module FbObject
+   module Read
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # @param graph [Koala::Facebook::API] A graph with access_token
+    # @param data [Hash] The properties you want to assign, this is what
+    #   facebook gave us (see known_keys).
+    # @param parent [<FbObject] A parent context for this class, must
+    #   inherit from {Zuck::FbObject}
+    def initialize(graph, data = {}, parent=nil)
+      self.graph = graph
+      set_data(data)
+
+      # If the parent is an {AdAccount} we only want to set it as this
+      # object's direct parent when this object is an {AdCampaign}.
+      if !parent.is_a?(AdAccount) or parent.is_a?(AdAccount) and self.is_a?(AdCampaign)
+        set_parent(parent)
+      end
+    end
+
+    # Refetches the data from façeboko
+    def reload
+      data = get(graph, path)
+      validate_data(data)
+      set_data(data)
+      self
+    end
+
+    private
+
+    # Sets the parent of this instance
+    #
+    # @param parent [FbObject] Has to be of the same class type you defined
+    #   using {FbObject.parent_object}
+    def set_parent(parent)
+      return unless parent
+      self.class.validate_parent_object_class(parent)
+      @parent_object = parent
+    end
+
+    # Makes sure that the data passed comes from a facebook
+    # object of the same type. We check this by comparing
+    # the 'group_id' value or the 'ad_group_id' value 
+    # with the 'id' value, when this
+    # is called on a {Zuck::AdGroup} for example.
+    #
+    # Facebook omits the "ad" prefix sometimes, so we check 
+    # for both.
+    def validate_data(data)
+      singular_list_path = self.class.list_path.to_s.singularize
+
+      # This is a special case for ad accounts (they have weird ids
+      # that begin with act: "act_12345" instead of "12345"
+      return if data['account_id'] and "act_#{data['account_id']}"  == data['id'].to_s
+
+      # This is the case for all other objects
+      long_id_key  = "#{singular_list_path}_id"
+      short_id_key = "#{singular_list_path[2..-1]}_id"
+      return if data[long_id_key]  and data[long_id_key].to_s  == data["id"].to_s
+      return if data[short_id_key] and data[short_id_key].to_s == data["id"].to_s
+
+      # Something went wrong. Either the data provided by the user is
+      # not consistent, or a wrong object type was belongs to this id on facebook
+      # (an ad group instead of an ad campaign, for example).
+      #
+      # Maybe we can make somebody's life easier by raising a verbose exception.
+      error = "Invalid type.\n\nExpected data['id']=#{data['id'].inspect} to be equal to one of these:\n"
+      error += "  * data['account_id']=#{data['account_id'].inspect}\n"
+      error += "  * data['#{short_id_key}']=#{data[short_id_key].inspect}\n"
+      error += "  * data['#{long_id_key}']=#{data[long_id_key].inspect}\n"
+
+      raise error
+    end
+
+    module ClassMethods
+
+      # Finds by object id and checks type
+      def find(id, graph = Zuck.graph)
+        new(graph, id: id).reload
+      end
+
+      # Automatique all getter.
+      #
+      # Let's say you want to fetch all campaigns
+      # from facebook. This can happen in the context of an ad
+      # account. In this gem, that context is called a parent. This method
+      # would only be called on objects that inherit from {FbObject}.
+      # It asks the `parent` for it's path (if it is given), and appends
+      # it's own `list_path` property that you have defined (see
+      # list_path)
+      #
+      # If, however, you want to fetch all ad creatives, regardless of
+      # which ad group is their parent, you can omit the `parent`
+      # parameter. The creatives returned by `Zuck::AdCreative.all` will
+      # return `nil` when you call `#ad_group` on them, though, because facebook
+      # will not return this information. So if you can, try to fetch 
+      # objects through their direct parent, e.g.
+      # `my_ad_group.ad_creatives`.
+      #
+      # @param graph [Koala::Facebook::API] A graph with access_token
+      # @param parent [<FbObject] A parent object to scope
+      def all(graph = Zuck.graph, parent = nil)
+        parent ||= parent_ad_account_fallback
+        r = get(graph, path_with_parent(parent))
+        r.map do |c|
+          new(graph, c, parent)
+        end
+      end
+
+      # Makes sure the given parent matches what you defined
+      # in {FbObject.parent_object}
+      def validate_parent_object_class(parent)
+        resolve_parent_object_class
+        e = "Invalid parent_object: #{parent.class} is not a #{@parent_object_class}"
+        raise e if @parent_object_class and !parent.is_a?(@parent_object_class)
+      end
+
+      private
+
+
+      # Attempts to resolve the {FbObject.parent_object} to a class at runtime
+      # so we can load files in any random order...
+      def resolve_parent_object_class
+        return if @parent_object_class
+        class_s = "Zuck::#{@parent_object_type.camelcase}"
+        @parent_object_class = class_s.constantize
+      end
+
+      # Some objects can be fetched "per account" or "per parent
+      # object", e.g. you can fetch all ad creatives for your account
+      # or only for a special ad group.
+      #
+      # @return [nil, Zuck::FbObject] Returns the current ad account
+      #   unless you're calling `Zuck::AdAccount.all`. Then we return
+      #   nil because the ad account needs no parent.
+      def parent_ad_account_fallback
+        return nil if self == Zuck::AdAccount
+        Zuck::AdAccount.all.first
+      end
+
+    end
+   end
+ end
+end