zuck 0.1.0 → 0.2.0

data/CHANGELOG.markdown

@@ -1,3 +1,7 @@
+0.2.0
+-----
+- implement Facbook's [Oct 2013 breaking changes](https://developers.facebook.com/roadmap/#q4_2013)
+
 0.0.9
 -----
 - add Zuck::TargetingSpec.valid_countries? method to allow for country

data/README.markdown

@@ -88,6 +88,41 @@ group.ad_status
 => 3
 ```
 
+AdKeyword convenience methods
+--------
+
+```ruby
+graph = Zuck.graph
+
+# Search for keywords (to auto complete, for example) (yes, facebook sometimes returns ids as string and sometimes as numbers)
+Zuck::AdKeyword.search(graph, "Auto")
+=>  [
+      {:keyword=>"Auto", :id=>"6003156165433", :audience=>nil},
+      {:keyword=>"#Automobile", :id=>6003176678152, :audience=>97900000},
+      {:keyword=>"#Auto racing", :id=>6003146718552, :audience=>21800000},
+      {:keyword=>"#Auto mechanic", :id=>6003109384433, :audience=>14600000}
+    ]
+
+# Quickly check if a keyword is valid
+Zuck::AdKeyword.validate(graph, '#Eminem')
+=> {"#Eminem" => true}
+
+# Quickly check a couple of keywords
+Zuck::AdKeyword.validate(graph, ['#Eminem', 'Wil Ferel', 'Bronson'])
+=> {"#Eminem"=>true, "Bronson"=>true, "Wil Ferel"=>false}
+
+# Make a best guess on how a keyword is called on Facebook
+Zuck::AdKeyword.best_guess(graph, 'Disney')
+=> {:keyword=>"#The Walt Disney Company", :id=>6003270522085, :audience=>72500000}
+
+# Sometimes a best guess does not return a keyword with a # prefix, and that
+# means that we don't know the audience of that keyword:
+Zuck::AdKeyword.best_guess(graph, 'Moviepilot')
+=> {:keyword=>"Moviepilot", :id=>6003327847780, :audience=>nil}
+
+```
+
+
 Supported objects
 -----------------
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/zuck/facebook/ad_account.rb

@@ -4,28 +4,31 @@ module Zuck
     # The [fb docs](https://developers.facebook.com/docs/reference/ads-api/adaccount/)
     # were incomplete, so I added here what the graph explorer
     # actually returned.
-    known_keys :account_id,
+    known_keys :account_groups,
+               :account_id,
                :account_status,
+               :age,
+               :agency_client_declaration,
+               :amount_spent,
                :balance,
                :business_city,
                :business_country_code,
                :business_name,
                :business_state,
-               :business_street,
                :business_street2,
+               :business_street,
                :business_zip,
                :capabilities,
                :currency,
                :daily_spend_limit,
                :id,
                :is_personal,
-               :moo_default_bid,
-               :moo_default_conversion_bid,
                :name,
-               :notification_settings,
+               :spend_cap,
                :timezone_id,
                :timezone_name,
                :timezone_offset_hours_utc,
+               :tos_accepted,
                :users,
                :vat_status
 

data/lib/zuck/facebook/ad_campaign.rb

@@ -5,7 +5,6 @@ module Zuck
     # were incomplete, so I added here what the graph explorer
     # actually returned.
     known_keys :account_id,
-               :campaign_id,
                :campaign_status,
                :created_time,
                :daily_imps,

data/lib/zuck/facebook/ad_creative.rb

@@ -7,21 +7,22 @@ module Zuck
     # The [fb docs](https://developers.facebook.com/docs/reference/ads-api/adaccount/)
     # were incomplete, so I added here what the graph explorer
     # actually returned.
-    known_keys :alt_view_tags,
+    known_keys :name,
+               :type,
+               :object_id,
                :body,
-               :count_current_adgroups,
-               :creative_id,
-               :id,
                :image_hash,
                :image_url,
+               :id,
+               :title,
                :link_url,
-               :name,
-               :object_id,
+               :url_tags,
                :preview_url,
-               :run_status,
-               :title,
-               :type,
-               :view_tag
+               :related_fan_page,
+               :follow_redirect,
+               :auto_update,
+               :story_id,
+               :action_spec
 
     parent_object :ad_group
     list_path     :adcreatives

data/lib/zuck/facebook/ad_group.rb

@@ -7,9 +7,6 @@ module Zuck
     # were incomplete, so I added here what the graph explorer
     # actually returned.
     known_keys :account_id,
-               :ad_id,
-               :ad_status,
-               :adgroup_id,
                :adgroup_status,
                :bid_info,
                :bid_type,
@@ -17,13 +14,14 @@ module Zuck
                :conversion_specs,
                :created_time,
                :creative_ids,
-               :end_time,
                :id,
-               :max_bid,
+               :disapprove_reason_descriptions,
+               :last_updated_by_app_id,
                :name,
-               :start_time,
                :targeting,
-               :updated_time
+               :tracking_specs,
+               :updated_time,
+               :view_tags
 
     parent_object :ad_campaign
     list_path     :adgroups

data/lib/zuck/fb_object/hash_delegator.rb

@@ -50,6 +50,11 @@ module Zuck
       def known_keys(*args)
         args.each do |key|
 
+          # Define list of known keys
+          self.send(:define_method, :known_keys) do
+            args || []
+          end
+
           # Define getter
           self.send(:define_method, key) do
             init_hash
@@ -106,6 +111,5 @@ module Zuck
     def init_hash
       @hash_delegator_hash ||= {}
     end
-
   end
 end

data/lib/zuck/fb_object/helpers.rb

@@ -6,7 +6,7 @@ module Zuck
 
       def get(graph, path)
         begin
-          graph.get_object(path)
+          graph.get_object(path, fields: known_keys.compact.join(','))
         rescue => e
           puts "#{e} graph.get_object(#{path.to_json})" if in_irb?
           raise e

data/lib/zuck/fb_object/read.rb

@@ -24,7 +24,6 @@ module Zuck
     # Refetches the data from façeboko
     def reload
       data = get(graph, path)
-      validate_data(data)
       set_data(data)
       self
     end
@@ -41,40 +40,6 @@ module Zuck
       @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

data/spec/fixtures/a_single_account.yml

@@ -2,74 +2,49 @@
 http_interactions:
 - request:
     method: get
-    uri: https://graph.facebook.com/act_10150585630710217?access_token=AAAEvJ5vzhl8BABhTSazJZB2D0B4N0l242VX22Hg9J2WZA7fptcAztfXxfAZB9mhZB6W1nl5dz5tXMlb9DJk9ibs6RqtP7PtO6a3XCiHWVwZDZD
+    uri: https://graph.facebook.com/act_10150585630710217?access_token=CAAEvJ5vzhl8BAH8aCPOx0Ft9uNB147TF8weJ8hK0g7YVDRWU4eEih7tEKdJgmfk0vABZClZACJbEzyhSMbiShL6RpsfkZASfX1C9nv1AlFvjJajflqkyYZAlpE2edT0FJHjdh4NFg0ZCt0sBgq0kZABtKsjuU18aMURLE7rjKHR4X8NkXBUafg1T4uZARRNqboZD&fields=account_groups,account_id,account_status,age,agency_client_declaration,amount_spent,balance,business_city,business_country_code,business_name,business_state,business_street2,business_street,business_zip,capabilities,currency,daily_spend_limit,id,is_personal,name,spend_cap,timezone_id,timezone_name,timezone_offset_hours_utc,tos_accepted,users,vat_status
     body:
       encoding: US-ASCII
       string: ''
     headers:
+      User-Agent:
+      - Faraday v0.8.7
       Accept-Encoding:
       - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
       Accept:
       - ! '*/*'
-      User-Agent:
-      - Ruby
   response:
     status:
       code: 200
-      message: !binary |-
-        T0s=
+      message: OK
     headers:
-      !binary "QWNjZXNzLUNvbnRyb2wtQWxsb3ctT3JpZ2lu":
-      - !binary |-
-        Kg==
-      !binary "Q2FjaGUtQ29udHJvbA==":
-      - !binary |-
-        cHJpdmF0ZSwgbm8tY2FjaGUsIG5vLXN0b3JlLCBtdXN0LXJldmFsaWRhdGU=
-      !binary "Q29udGVudC1UeXBl":
-      - !binary |-
-        dGV4dC9qYXZhc2NyaXB0OyBjaGFyc2V0PVVURi04
-      !binary "RXRhZw==":
-      - !binary |-
-        Ijc1NWUyMTBmYjE2N2NkOTQxNWI3ODIzZTZjOGM4YjYwYTQ1MzUwZTUi
-      !binary "RXhwaXJlcw==":
-      - !binary |-
-        U2F0LCAwMSBKYW4gMjAwMCAwMDowMDowMCBHTVQ=
-      !binary "UHJhZ21h":
-      - !binary |-
-        bm8tY2FjaGU=
-      !binary "WC1GYi1SZXY=":
-      - !binary |-
-        NjEyNTY1
-      !binary "Q29udGVudC1FbmNvZGluZw==":
-      - !binary |-
-        Z3ppcA==
-      !binary "WC1GYi1EZWJ1Zw==":
-      - !binary |-
-        L3l3UTJxVWc2L0toZVhhTnFXY21lVFFsSW0vVkFEV09tUFIvQVkzVWsxTT0=
-      !binary "RGF0ZQ==":
-      - !binary |-
-        VHVlLCAyMSBBdWcgMjAxMiAxNDo1MjoyNCBHTVQ=
-      !binary "Q29ubmVjdGlvbg==":
-      - !binary |-
-        a2VlcC1hbGl2ZQ==
-      !binary "Q29udGVudC1MZW5ndGg=":
-      - !binary |-
-        NTA1
+      Access-Control-Allow-Origin:
+      - ! '*'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Content-Type:
+      - application/json; charset=UTF-8
+      Etag:
+      - ! '"3974cd2e1bd6adde467a920e740351a73e2d5889"'
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      Pragma:
+      - no-cache
+      X-Fb-Rev:
+      - '934677'
+      X-Fb-Debug:
+      - X2mEeMJUPl6v6oa677ct5KWrnQJIEqYykFRDw7P1OOE=
+      Date:
+      - Thu, 12 Sep 2013 13:21:40 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '697'
     body:
-      encoding: ASCII-8BIT
-      string: !binary |-
-        H4sIAAAAAAAAA6VSTWvcMBD9K0anFgSV7LU361tDQqHQU8mlTRGyLO8OsSWj
-        j8Bm2f/e0W7i2MS3nOz39GbmzceJQEtqIlUQnPGSlTdlVbAtZznfEoq8stEE
-        cRGtCYwcND7NpD7IED2pOSUqOqeNOqLg4fcdagIM+sUafcm32c6I1zz30dlR
-        P3671a4HM4+wXed1EAcbnRcxKFLnlIAXo3beGtmTmlHSRA9Gey9e093CPvsF
-        Tzr73jvYH0L28CP7cpBdiGbvG+3VwT1GxvTGPIWvWG2K98FpHdD3JzPkmOLn
-        tcReO9Na12mX/dHQ66zi84oKQprT1PjMigxpxB9fXmBMW8lztltkShtzR6Fs
-        m+Lu7vHxWQbxtpiCklZCfxR+1KYVPQyAneYlYzjB6HGepP57IjHtqGR8W+At
-        VJTgoAfwHqxJ75zmtKAbWtLtP0qc7bEUZ4yfERkboAMlA2oFLi0ATpvUJzJl
-        SwDV7PLFwDNNEP/mEGd3hZTgb8WuomKV3SxDyyWslnC3gHzpgs9d5DOP7y6Q
-        nUQL9uL4zSuqVrwiO3ldxE6W39litTqyK9WRXVRHvFI97XjWfPUBzpvfrZa/
-        WWHPuBolR9lADwF0uo8c76CRvTQKDwPvarBWtLqTsQ94mOYZryxdR5OOLF3C
-        +T90T7SjiQQAAA==
+      encoding: US-ASCII
+      string: ! '{"account_id":"10150585630710217","account_status":1,"age":590.89847222222,"amount_spent":4093,"balance":0,"business_city":"Berlin","business_country_code":"DE","business_name":"Big
+        Mike Alright UG (haftungsbeschr\u00e4nkt)","business_state":"Berlin","business_street2":"J\u00e4gerndorfer
+        Zeile 61","business_street":"Big Mike Alright UG (haftungsbeschr\u00e4nkt)","business_zip":"12209","capabilities":[2,6,15,11,16],"currency":"USD","daily_spend_limit":150000,"id":"act_10150585630710217","is_personal":0,"name":"","spend_cap":5000,"timezone_id":47,"timezone_name":"Europe\/Berlin","timezone_offset_hours_utc":2,"users":[{"uid":501730216,"permissions":[1,2,3,4,5,7],"role":1001}],"vat_status":3}'
     http_version: 
-  recorded_at: Tue, 21 Aug 2012 14:52:25 GMT
-recorded_with: VCR 2.2.4
+  recorded_at: Thu, 12 Sep 2013 13:21:40 GMT
+recorded_with: VCR 2.3.0

data/spec/fixtures/a_single_campaign.yml

@@ -2,17 +2,17 @@
 http_interactions:
 - request:
     method: get
-    uri: https://graph.facebook.com/6005950787751?access_token=AAAEvJ5vzhl8BABhTSazJZB2D0B4N0l242VX22Hg9J2WZA7fptcAztfXxfAZB9mhZB6W1nl5dz5tXMlb9DJk9ibs6RqtP7PtO6a3XCiHWVwZDZD
+    uri: https://graph.facebook.com/6005950787751?access_token=CAAEvJ5vzhl8BAH8aCPOx0Ft9uNB147TF8weJ8hK0g7YVDRWU4eEih7tEKdJgmfk0vABZClZACJbEzyhSMbiShL6RpsfkZASfX1C9nv1AlFvjJajflqkyYZAlpE2edT0FJHjdh4NFg0ZCt0sBgq0kZABtKsjuU18aMURLE7rjKHR4X8NkXBUafg1T4uZARRNqboZD&fields=account_id,campaign_status,created_time,daily_imps,end_time,id,lifetime_budget,name,start_time,updated_time
     body:
       encoding: US-ASCII
       string: ''
     headers:
+      User-Agent:
+      - Faraday v0.8.7
       Accept-Encoding:
       - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
       Accept:
       - ! '*/*'
-      User-Agent:
-      - Ruby
   response:
     status:
       code: 200
@@ -23,26 +23,26 @@ http_interactions:
       Cache-Control:
       - private, no-cache, no-store, must-revalidate
       Content-Type:
-      - text/javascript; charset=UTF-8
+      - application/json; charset=UTF-8
       Etag:
-      - ! '"050868a2c006f558b70017a737ca8f72419e7bc1"'
+      - ! '"e86bfdbd29a6618779f20e958e1dfe705bb806de"'
       Expires:
       - Sat, 01 Jan 2000 00:00:00 GMT
       Pragma:
       - no-cache
       X-Fb-Rev:
-      - '612565'
+      - '934677'
       X-Fb-Debug:
-      - o5ZT1cHA5d8AdQpUe+7pBF0kc5dqhirTcSEjdEaM7m8=
+      - i6CJnwde2dK30oFKSKB+yrtbjQtBwOx7j7wbo7jQdwQ=
       Date:
-      - Tue, 21 Aug 2012 14:13:01 GMT
+      - Thu, 12 Sep 2013 13:21:40 GMT
       Connection:
       - keep-alive
       Content-Length:
-      - '294'
+      - '230'
     body:
       encoding: US-ASCII
-      string: ! '{"account_id":"10150585630710217","campaign_id":6005950787751,"name":"bloody","daily_budget":1000,"campaign_status":1,"daily_imps":0,"id":"6005950787751","start_time":"2012-08-21T14:04:13+0000","end_time":null,"updated_time":"2012-08-21T14:08:34+0000","created_time":"2012-08-21T14:04:13+0000"}'
+      string: ! '{"account_id":"10150585630710217","campaign_status":3,"created_time":"2012-08-21T16:04:13+0200","daily_imps":0,"id":"6005950787751","name":"bloody","start_time":"2012-08-21T16:04:13+0200","updated_time":"2013-03-25T12:40:29+0100"}'
     http_version: 
-  recorded_at: Tue, 21 Aug 2012 14:13:02 GMT
-recorded_with: VCR 2.2.4
+  recorded_at: Thu, 12 Sep 2013 13:21:40 GMT
+recorded_with: VCR 2.3.0

data/spec/fixtures/a_single_group.yml

@@ -0,0 +1,48 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://graph.facebook.com/6010889111951?access_token=CAAEvJ5vzhl8BAH8aCPOx0Ft9uNB147TF8weJ8hK0g7YVDRWU4eEih7tEKdJgmfk0vABZClZACJbEzyhSMbiShL6RpsfkZASfX1C9nv1AlFvjJajflqkyYZAlpE2edT0FJHjdh4NFg0ZCt0sBgq0kZABtKsjuU18aMURLE7rjKHR4X8NkXBUafg1T4uZARRNqboZD&fields=account_id,adgroup_status,bid_info,bid_type,campaign_id,conversion_specs,created_time,creative_ids,id,disapprove_reason_descriptions,last_updated_by_app_id,name,targeting,tracking_specs,updated_time,view_tags
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - Faraday v0.8.7
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - ! '*/*'
+  response:
+    status:
+      code: 400
+      message: Bad Request
+    headers:
+      Access-Control-Allow-Origin:
+      - ! '*'
+      Cache-Control:
+      - no-store
+      Content-Type:
+      - application/json; charset=UTF-8
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      Pragma:
+      - no-cache
+      Www-Authenticate:
+      - ! 'OAuth "Facebook Platform" "invalid_request" "(#100) Unknown fields: adgroup_status,bid_info,bid_type,conversion_specs,creative_ids,disapprove_reason_descriptions,last_updated_by_app_id,targeting,tracking_specs,view_tags."'
+      X-Fb-Rev:
+      - '934677'
+      X-Fb-Debug:
+      - Gks1Vwa18J2bq9/Zxb9ya6ywWnVPynwEDSmFjSxKc9k=
+      Date:
+      - Thu, 12 Sep 2013 13:21:40 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '234'
+    body:
+      encoding: US-ASCII
+      string: ! '{"error":{"message":"(#100) Unknown fields: adgroup_status,bid_info,bid_type,conversion_specs,creative_ids,disapprove_reason_descriptions,last_updated_by_app_id,targeting,tracking_specs,view_tags.","type":"OAuthException","code":100}}'
+    http_version: 
+  recorded_at: Thu, 12 Sep 2013 13:21:41 GMT
+recorded_with: VCR 2.3.0