zuck 0.0.4

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use ruby-1.9.3@zuck

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - "1.9.2"
+  - "1.9.3"
+  - jruby-19mode
+  - rbx-19mode
+script: bundle exec rspec spec

data/.yardopts

@@ -0,0 +1,4 @@
+--hide-void-return
+--no-output
+--markup-provider=redcarpet
+--markup=markdown

data/CHANGELOG.markdown

@@ -0,0 +1,4 @@
+0.0.4
+-----
+
+- integrated targeting spec to fetch reach estimates

data/Gemfile

@@ -0,0 +1,35 @@
+source 'http://rubygems.org'
+
+gem 'rvm'
+gem 'bundler'
+gem 'koala', '>=1.5'
+gem 'activesupport'
+
+group :development do
+  gem "shoulda", ">= 0"
+  gem "rdoc", "~> 3.12"
+  gem "jeweler", "~> 1.8.4"
+  gem "simplecov", ">= 0", :require => false
+end
+
+group :development, :test do
+  gem 'webmock'
+  gem 'rspec'
+  gem 'vcr'
+end
+
+platform :ruby do
+  group :development do
+    gem 'guard'
+    gem 'guard-rspec'
+    gem 'guard-bundler'
+    gem 'guard-yard'
+    gem 'growl'
+    gem 'redcarpet'    # Markdown for yard
+    gem 'rb-fsevent'
+  end
+end
+
+# platform :jruby do
+#   # gem 'jruby-openssl'
+# end

data/Gemfile.lock

@@ -0,0 +1,110 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.2.9)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    addressable (2.3.2)
+    bourne (1.1.2)
+      mocha (= 0.10.5)
+    coderay (1.0.8)
+    crack (0.3.1)
+    diff-lcs (1.1.3)
+    faraday (0.8.4)
+      multipart-post (~> 1.1)
+    git (1.2.5)
+    growl (1.0.3)
+    guard (1.6.1)
+      listen (>= 0.6.0)
+      lumberjack (>= 1.0.2)
+      pry (>= 0.9.10)
+      thor (>= 0.14.6)
+    guard-bundler (1.0.0)
+      bundler (~> 1.0)
+      guard (~> 1.1)
+    guard-rspec (2.3.3)
+      guard (>= 1.1)
+      rspec (~> 2.11)
+    guard-yard (2.0.1)
+      guard (>= 1.1.0)
+      yard (>= 0.7.0)
+    i18n (0.6.1)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.5)
+    json (1.7.5-java)
+    koala (1.6.0)
+      addressable (~> 2.2)
+      faraday (~> 0.8)
+      multi_json (~> 1.3)
+    listen (0.6.0)
+    lumberjack (1.0.2)
+    metaclass (0.0.1)
+    method_source (0.8.1)
+    mocha (0.10.5)
+      metaclass (~> 0.0.1)
+    multi_json (1.5.0)
+    multipart-post (1.1.5)
+    pry (0.9.10)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.3.1)
+    rake (10.0.3)
+    rb-fsevent (0.9.1)
+    rdoc (3.12)
+      json (~> 1.4)
+    redcarpet (2.2.2)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.1)
+    rvm (1.11.3.5)
+    shoulda (3.3.2)
+      shoulda-context (~> 1.0.1)
+      shoulda-matchers (~> 1.4.1)
+    shoulda-context (1.0.2)
+    shoulda-matchers (1.4.2)
+      activesupport (>= 3.0.0)
+      bourne (~> 1.1.2)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    slop (3.3.3)
+    thor (0.16.0)
+    vcr (2.3.0)
+    webmock (1.9.0)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+    yard (0.8.3)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  activesupport
+  bundler
+  growl
+  guard
+  guard-bundler
+  guard-rspec
+  guard-yard
+  jeweler (~> 1.8.4)
+  koala (>= 1.5)
+  rb-fsevent
+  rdoc (~> 3.12)
+  redcarpet
+  rspec
+  rvm
+  shoulda
+  simplecov
+  vcr
+  webmock

data/Guardfile.dist

@@ -0,0 +1,45 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'bundler' do
+  watch('Gemfile')
+  # Uncomment next line if Gemfile contain `gemspec' command
+  # watch(/^.+\.gemspec/)
+end
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch('spec/spec_helper.rb')  { "spec" }
+  watch(%r{^lib/zuck/(.+)\.rb$})  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+
+
+guard 'spork', :cucumber_env => { 'RAILS_ENV' => 'test' }, :rspec_env => { 'RAILS_ENV' => 'test' } do
+  watch('config/application.rb')
+  watch('config/environment.rb')
+  watch('config/environments/test.rb')
+  watch(%r{^config/initializers/.+\.rb$})
+  watch('Gemfile')
+  watch('Gemfile.lock')
+  watch('spec/spec_helper.rb') { :rspec }
+  watch('test/test_helper.rb') { :test_unit }
+  watch(%r{features/support/}) { :cucumber }
+end
+
+guard 'yard' do
+  watch(%r{app/.+\.rb})
+  watch(%r{lib/.+\.rb})
+  watch(%r{ext/.+\.c})
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Jannis Hermanns
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,138 @@
+[![Build Status](https://secure.travis-ci.org/moviepilot/zuck.png?branch=master)](https://travis-ci.org/moviepilot/zuck)
+
+Zuck; use facebook's advertisement API with ruby
+================
+
+This is a little gem that makes access to facebook's 
+ads API a little easier. Check out facebook's
+[documentation](https://developers.facebook.com/docs/reference/ads-api/)
+for a nice diagram that explains how things work.
+
+![](https://dl.dropbox.com/u/1953503/kw29_koelner_gelierzucker_31_oder_diamant_feinster_zucker_462982.jpeg)
+
+We just hacked this up and are not using it in production yet,
+so handle with care. On the other hand, simplecov reports 100%
+coverage. But as it is a gem in a very early stage, a warning was
+due.
+
+Usage
+=====
+
+Not everything is supported yet. Here's what you can do currently.
+
+
+Reading
+--------
+```ruby
+# Let's set a default graph object with an access token
+Zuck.graph = Koala::Facebook::API.new('my_access_token')
+
+# Fetching all ad accounts associated to that user
+accounts = Zuck::AdAccount.all
+
+# Let's look at an account
+my_account = accounts.first
+=> #<Zuck::AdAccount id: "act_10150585630710217", account_id: "10150585630710217", name: "", account_status: 1, currency: "USD", timezone_id: 47, timezone_name: "Europe/Berlin", timezone_offset_hours_utc: 2, is_personal: 0, business_name: "Big Mike Alright UG (haftungsbeschr\u00e4nkt)", business_street: "Big Mike Alright UG (haftungsbeschr\u00e4nkt)", business_street2: "J\u00e4gerndorfer Zeile 61", business_city: "Berlin", business_state: "Berlin", business_zip: "12209", business_country_code: "DE", vat_status: 3, daily_spend_limit: 25000, users: [{"uid":501730216,"permissions":[1,2,3,4,5,7],"role":1001}], notification_settings: {"501730216":{"1000":{"1":1},"1001":{"1":1},"1002":{"1":1,"2":60},"1003":{"1":1,"2":60},"1004":{"1":1},"1005":{"1":1},"1006":{"1":1},"1009":{"1":1},"1010":{"1":1},"1011":{"1":1},"2000":{"1":1,"2":60},"2001":{"1":1,"2":60},"2002":{"2":60},"2003":{"1":1,"2":60},"2004":{"1":1,"2":60},"2005":{"1":1,"2":60},"3000":{"1":1,"2":60},"3001":{"1":1,"2":60},"3002":{"2":60},"3003":{"1":1,"2":60},"5000":{"1":1},"6000":{"1":1},"6001":{"1":1},"9000":{"1":1,"2":60},"8000":{"1":1,"2":60}}}, capabilities: [], balance: 0, moo_default_conversion_bid: 1000, moo_default_bid: 1000> 
+
+# Aha. How do I access properties? The documented properties
+# have getters:
+my_account.currency
+=> "USD"    
+
+# But facebook also returns some non documented stuff
+my_account[:moo_default_bid]
+=> 1000
+
+# Let's fetch the campaigns for this account
+my_campaign = my_account.ad_campaigns.first
+
+# Aha! Does this campaign have ad groups?
+my_group = my_campaign.ad_groups.first
+my_group.name
+=> "Group names are silly"
+
+# That was surprising. Just like the fact that ad groups
+# have ad creatives associated to them:
+my_creative = my_group.ad_creatives.first
+
+# Let's go back up to the parent
+my_creative.ad_group.name
+=> "Group names are silly"
+```
+
+Writing
+--------
+
+```ruby
+# Directly defining the creative as JSON
+creative = '{"type":25,"action_spec":{"action.type":"like", "post":10150420410887685}}'
+
+# Options for the ad group we want to create
+o = { bid_type:  1,
+      max_bid:   1,
+      name:      "My first ad group",
+      targeting: '{"countries":["US"]}',
+      creative:  creative}
+      
+# Create it in the context of my_campaign
+group = my_campaign.create_ad_group(o)
+=> #<Zuck::AdGroup adgroup_id: 6005851390151, ad_id: 6005851390151, campaign_id: 6005851032951, name: "My first ad group", adgroup_status: 4, bid_type: 1, max_bid: "1", bid_info: {"1":"1"}, ad_status: 4, account_id: "10150585630710217", id: "6005851390151", creative_ids: [6005851371551], targeting: {"countries":["US"],"friends_of_connections":[{"id":"6005851366351","name":null}]}, conversion_specs: [{"action.type":"like","post":"10150420410887685"}], start_time: null, end_time: null, updated_time: 1343916568, created_time: 1343916568>
+
+# Shoot, that was the wrong name
+group.name = "My serious ad group"
+group.save
+=> true
+
+# No wait, let's not spend money on facebook
+group.destroy
+=> true
+
+# What does destroy mean? Changing the status!
+group.ad_status
+=> 3
+```
+
+Supported objects
+-----------------
+
+This gem supports basic CRUD on the objects of the facebook ads api.
+Here's a support chart:
+
+<table>
+  <tr>
+    <th style="text-align:right">Object</th>
+    <th style="text-align:center">.all</th>
+    <th style="text-align:center">.create</th>
+    <th style="text-align:center">.save</th>
+    <th style="text-align:center">.destroy</th>
+    <th style="text-align:center">parent.create_obj*</th>
+    <th style="text-align:center">Convenience methods**</th>
+  </tr>
+  <tr><td style="text-align: right">Ad account</td>       <td>✔</td><td>-</td><td>✔</td><td>✔</td><td>-</td><td>-</td></tr>
+  <tr><td style="text-align: right">Ad account group</td> <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
+  <tr><td style="text-align: right">Ad campaign</td>      <td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>-</td></tr>
+  <tr><td style="text-align: right">Ad creative</td>      <td>✔</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
+  <tr><td style="text-align: right">Ad group</td>         <td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>✔</td><td>-</td></tr>
+  <tr><td style="text-align: right">Ad image</td>         <td>●</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
+  <tr><td style="text-align: right">Ad user</td>          <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
+</table>
+
+(*) This means that you can, for example, create a new ad group by calling
+`my_campaign.create_ad_group(data)` or not.
+
+(**) Right now, everything goes right to facebook, but we'll want some 
+convenience methods that tell you, for example, what
+`ad_group.ad_status == 3` actually means
+
+( ) These don't exist as their own objects in this gem but live in their 
+parents. This means you can, for now, only read them:
+
+Users don't exist as objects yet, but you can list all ad users of
+an account via `my_ad_account.users` and you will get an array of hashes.
+
+To-Do
+-----
+
+Add convenience stuff, right now everything is quite raw and directly
+sent over to facebook. Also, more tests directly to the api with a test
+user. Consolidate and test create code with other objects than AdGroup.

data/Rakefile

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "zuck"
+  gem.homepage = "http://github.com/jayniz/zuck"
+  gem.license = "MIT"
+  gem.summary = %Q{Ruby adapter to facebook's ad api}
+  gem.description = %Q{This gem allows to easily access facebook's ads api in ruby. See https://developers.facebook.com/docs/reference/ads-api/}
+  gem.email = "jannis@gmail.com"
+  gem.authors = ["Jannis Hermanns"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "zuck #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.4

data/console

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), 'lib'))
+
+require 'bundler'
+Bundler.require
+
+require 'irb'
+require 'zuck'
+
+def reload!
+  @loaded_files ||= {}
+  count = 0
+
+  Dir['./lib/**/*.rb'].each do |file|
+    mtime = File.stat(file).mtime
+    if !@loaded_files.has_key?(file) or mtime > @loaded_files[file]
+      STDERR.puts "mtime for #{file} changed, reloading"
+      load file
+      @loaded_files[file] = mtime
+      count += 1
+    end
+  end
+  "reloaded #{count} files"
+end
+
+IRB.start

data/lib/zuck/facebook/ad_account.rb

@@ -0,0 +1,40 @@
+module Zuck
+  class AdAccount < RawFbObject
+
+    # 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,
+               :account_status,
+               :balance,
+               :business_city,
+               :business_country_code,
+               :business_name,
+               :business_state,
+               :business_street,
+               :business_street2,
+               :business_zip,
+               :capabilities,
+               :currency,
+               :daily_spend_limit,
+               :id,
+               :is_personal,
+               :moo_default_bid,
+               :moo_default_conversion_bid,
+               :name,
+               :notification_settings,
+               :timezone_id,
+               :timezone_name,
+               :timezone_offset_hours_utc,
+               :users,
+               :vat_status
+
+
+    list_path   'me/adaccounts'
+    connections :ad_campaigns
+
+    def self.all(graph = Zuck.graph)
+      super(graph)
+    end
+  end
+end

data/lib/zuck/facebook/ad_campaign.rb

@@ -0,0 +1,24 @@
+module Zuck
+  class AdCampaign < RawFbObject
+
+    # 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,
+               :campaign_id,
+               :campaign_status,
+               :created_time,
+               :daily_imps,
+               :end_time,
+               :id,
+               :lifetime_budget,
+               :name,
+               :start_time,
+               :updated_time
+
+    parent_object :ad_account
+    list_path     :adcampaigns
+    connections   :ad_groups
+
+  end
+end

data/lib/zuck/facebook/ad_creative.rb

@@ -0,0 +1,30 @@
+module Zuck
+  class AdCreative < RawFbObject
+
+    # Can't create this directly (yet)
+    read_only
+
+    # 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,
+               :body,
+               :count_current_adgroups,
+               :creative_id,
+               :id,
+               :image_hash,
+               :image_url,
+               :link_url,
+               :name,
+               :object_id,
+               :preview_url,
+               :run_status,
+               :title,
+               :type,
+               :view_tag
+
+    parent_object :ad_group
+    list_path     :adcreatives
+
+  end
+end

data/lib/zuck/facebook/ad_group.rb

@@ -0,0 +1,39 @@
+require 'zuck/facebook/ad_creative'
+
+module Zuck
+  class AdGroup < RawFbObject
+
+    # 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,
+               :ad_id,
+               :ad_status,
+               :adgroup_id,
+               :adgroup_status,
+               :bid_info,
+               :bid_type,
+               :campaign_id,
+               :conversion_specs,
+               :created_time,
+               :creative_ids,
+               :end_time,
+               :id,
+               :max_bid,
+               :name,
+               :start_time,
+               :targeting,
+               :updated_time
+
+    parent_object :ad_campaign
+    list_path     :adgroups
+    connections   :ad_creatives
+
+    def self.create(graph, data, ad_campaign)
+      path = ad_campaign.ad_account.path
+      data['campaign_id'] = ad_campaign.id
+      super(graph, data, ad_campaign, path)
+    end
+
+  end
+end