fourmer 1.0.0

data/.autotest

@@ -0,0 +1,27 @@
+require 'autotest/growl'
+require 'autotest/fsevent'
+require 'redgreen/autotest'
+require 'autotest/restart'
+
+module Autotest::Growl
+  def self.growl title, msg, img, pri=0, stick=""
+    system "growlnotify -n autotest --image #{img} -p #{pri} -m #{ msg.inspect} #{title} #{stick}"
+  end
+
+  Autotest.add_hook :ran_command do |autotest|
+    filtered = autotest.results.grep(/\d+\s.*tests?/)
+
+    output = filtered.empty? ? "" : filtered.last.slice(/(\d+)\s.*tests?,\s(\d+)\s.*assertions?,\s(\d+)\s.*failures?,\s(\d+)\s.*errors?/)
+    if output =~ /[1-9]\sfailures?/ or output =~ /[1-9]\serrors?/
+      growl "Test Results", "#{output}", "~/Library/Autotest/rails_fail.png"
+    else
+      growl "Test Results", "#{output}", "~/Library/Autotest/rails_ok.png"
+    end
+
+  end
+
+end
+
+Autotest.add_hook :initialize do |at|
+  %w{.svn .hg .git vendor}.each {|exception| at.add_exception(exception)}
+end

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+gem "httparty", ">= 0"
+gem "hashie", ">= 1.1.0"
+
+group :development do
+  gem "mocha",   ">= 0"
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.4"
+  gem "rcov", ">= 0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Tim Olshansky
+
+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.md

@@ -0,0 +1,124 @@
+# fourmer
+
+fourmer is an unofficial wrapper for the [Foursquare Merchant API](https://developer.foursquare.com/merchant/).
+
+fourmer makes it easy for you to create new campaigns, specials and venue groups for the venues you manage.
+
+## Installation
+
+Fourmer is distributed as a gem, which is how it should be used in your app. Assuming you have rubygems or bundler, simply do the following:
+
+    gem install fourmer
+
+Or include the gem in your Gemfile.
+
+    gem "fourmer", ">= 0"
+
+## Usage
+
+Fourmer is designed to be as simple to use as possible, to mimic the layout and actions available in the Foursquare Merchant API.
+
+### Web Applications
+
+Initialize your consumer with userless access:
+
+    merchant = Foursquare::Merchant::Consumer.new('CLIENT_ID', 'CLIENT_SECRET')
+
+Redirect users to the Foursquare authentication page:
+
+    # If using Rails:
+    redirect_to merchant.authorize_url('YOUR_CALLBACK_URL')
+    
+    # Otherwise, redirect your users to:
+    merchant.authorize_url('YOUR_CALLBACK_URL')
+
+The user will then be asked whether to authorize your application. If the user accepts, then Foursquare will redirect the user to your callback url (`YOUR_CALLBACK_URL`) with a `code` in the url. You then exchange this `code` for an access token:
+
+    access_token = merchant.access_token(params[:code], 'YOUR_CALLBACK_URL')
+
+You can then make requests on the user's behalf by re-initializing your consumer:
+
+    merchant = Foursquare::Merchant::Consumer.new(access_token)
+
+For a description of the Foursquare Authentication flow, go [here](https://developer.foursquare.com/merchant/oauth.html).
+
+### Quick Start
+
+Initialize your consumer:
+
+    merchant = Foursquare::Merchant::Base.new('ACCESS_TOKEN')
+
+Or for userless access (only works for some objects and actions, such as venue search):
+
+    merchant = Foursquare::Merchant::Base.new('CLIENT_ID', 'CLIENT_SECRET')
+
+#### Campaigns
+
+Find an existing campaign:
+
+    campaign = merchant.campaigns.find('campaign_id')
+    #=> #<Foursquare::Merchant::Campaign: ...>
+
+Delete an existing campaign that has never been activated:
+
+    campaign.delete
+    #=> nil
+
+#### Specials
+
+Get a list of all specials for the current user:
+
+    specials = merchant.specials.list
+    #=> [#<Foursquare::Merchant::Special: ...>, ...]
+
+Create a new special:
+
+    params = { 'text' => 'Some text', 'unlockedText' => 'Some other text', ... }
+    special = merchant.specials.add(params)
+    #=> #<Foursquare::Merchant::Special: ...>
+
+#### Venuegroups
+
+Create a new venue group:
+
+    venuegroup = merchant.venue_groups.add('NAME_OF_VENUEGROUP')
+    #=> #<Foursquare::Merchant::Venuegroup: ...>
+    
+Add venues to it:
+
+    venues = [#<Foursquare::Merchant::Venue: ...>, ...]
+    venuegroup.addvenue(venues)
+    #=> nil
+
+Note that venues can either be a single venue id string/venue object, an array of venue ids, or an array of venue objects.
+
+#### Venues
+
+Get a list of all of the venues managed by the user:
+
+    managed_venues = merchant.venues.managed
+    #=> [#<Foursquare::Merchant::Venue: ...>, ...]
+
+Edit a venue managed by the user:
+
+    venue = merchant.venues.find('VENUE_ID')
+    venue.update({'url' => 'http://some.domain.com/'})
+    #=> #<Foursquare::Merchant::Venue: ...>
+
+See the [Foursquare Merchant API](https://developer.foursquare.com/merchant/) for further actions available for campaigns, specials, venuegroups and venues.
+
+## Contributing to fourmer
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011 Tim Olshansky. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,53 @@
+# 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 = "fourmer"
+  gem.homepage = "http://github.com/timols/fourmer"
+  gem.license = "MIT"
+  gem.summary = %Q{An unofficial wrapper for the Foursquare Merchant API}
+  gem.description = %Q{An easy to use library for interacting with the Foursquare Merchant API}
+  gem.email = "tim.olshansky@gmail.com"
+  gem.authors = ["Tim Olshansky"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "fourmer #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/fourmer.rb

@@ -0,0 +1,20 @@
+$LOAD_PATH << File.dirname(__FILE__)
+
+require 'rubygems'
+require 'hashie'
+require 'httparty'
+require 'foursquare/requests'
+require 'foursquare/base'
+require 'foursquare/model'
+require 'foursquare/campaigns'
+require 'foursquare/campaign'
+require 'foursquare/consumer'
+require 'foursquare/errors'
+require 'foursquare/specials'
+require 'foursquare/special'
+require 'foursquare/timeseries'
+require 'foursquare/venue_groups'
+require 'foursquare/venue_group'
+require 'foursquare/venues'
+require 'foursquare/venue'
+require 'foursquare/venue_stats'

data/lib/foursquare/base.rb

@@ -0,0 +1,32 @@
+module Foursquare
+  module Merchant
+
+    class Base
+      include HTTParty
+      include Merchant::Requests
+
+      base_uri Merchant::Requests::API
+      format :json
+
+      attr_accessor :consumer
+      def initialize(consumer)
+        @consumer = consumer
+      end
+
+      private
+        def listify(venues)
+          case venues
+          when Array
+            venues.join(',')
+          when String
+            venues
+          else
+            raise ArgumentError, "Please ensure you're attempting to use either an " +
+                                 "array of venue ids, or a comma delimited list of ids"
+          end
+        end
+
+    end
+
+  end
+end

data/lib/foursquare/campaign.rb

@@ -0,0 +1,49 @@
+module Foursquare
+  module Merchant
+
+    class Campaign < Model
+      property :venue_group_ids,  :from => :venueGroupIds
+      property :starts_at,        :from => :startsAt
+      property :ends_at,          :from => :endsAt
+      property :venue_ids,        :from => :venues
+      property :special_id,       :from => :specialId
+      property :venue_groups,     :from => :venueGroups
+      property :id
+      property :special
+
+      def initialize(hash, consumer)
+        super
+        self.venue_ids       = self.venue_ids['items'].map { |item| item['id'] } if self.venue_ids
+        self.venue_group_ids = self.venue_group_ids['items'].map { |item| item['id'] } if self.venue_group_ids
+        self.venue_groups    = self.venue_groups['items'].map { |item| item['id'] } if self.venue_groups
+        self.special         = Special.new(self.special, consumer) if self.special
+      end
+
+      def timeseries(start_time=nil, end_time=nil)
+        params = {}
+        params[:start_at] = start_time if start_time
+        params[:end_at]   = end_time if end_time
+
+        response = self.get("/campaigns/#{id}/timeseries", params)['timeseries']
+        response.map { |ts| TimeSeries.new(ts) }
+      end
+
+      def start(start_time=nil)
+        params = {}
+        params[:start_at] = start_time if start_time
+        self.post("/campaigns/#{id}/start", params)
+      end
+
+      def end(end_time=nil)
+        params = {}
+        params[:end_at] = end_time if end_time
+        self.post("/campaigns/#{id}/start", params)
+      end
+
+      def delete
+        self.post("/campaigns/#{id}/delete", {})
+      end
+    end
+
+  end
+end

data/lib/foursquare/campaigns.rb

@@ -0,0 +1,25 @@
+module Foursquare
+  module Merchant
+
+    class Campaigns < Base
+      base_uri "#{API}/campaigns"
+
+      def find(campaign_id, params={})
+        response = self.get("/#{campaign_id}", params)
+        Foursquare::Merchant::Campaign.new(response['campaign'], @consumer)
+      end
+
+      def add(params)
+        response = self.post("/add", params)
+        Foursquare::Merchant::Campaign.new(response['campaign'], @consumer)
+      end
+
+      def list(params={})
+        response = self.get("/list", params)
+        campaigns = response['campaigns']['items']
+        campaigns.map { |item| Foursquare::Merchant::Campaign.new(item, @consumer) }
+      end
+    end
+
+  end
+end

data/lib/foursquare/consumer.rb

@@ -0,0 +1,62 @@
+module Foursquare
+  module Merchant
+
+    class Consumer < Base
+      base_uri Merchant::Requests::OAUTH
+
+      attr_reader :oauth_token, :client_id, :client_secret
+      def initialize(*args)
+        if args.size == 1
+          @oauth_token = args.first
+        elsif args.size == 2
+          @client_id, @client_secret = args
+        else
+          raise ArgumentError, "Please include either an access token or client id & secret"
+        end
+      end
+
+      def authorize_url(callback_url)
+        raise ArgumentError.new("Please use a valid client_id") unless @client_id
+        if callback_url =~ /http/
+          query = {
+            :client_id => @client_id,
+            :response_type => 'code',
+            :redirect_uri => callback_url
+          }.map { |k,v| "#{k}=#{v}"}.join('&')
+          "#{OAUTH}/authenticate?#{query}"
+        else
+          raise ArgumentError, "Please ensure you specify a valid callback url, including the protocol (http://)"
+        end
+      end
+
+      def access_token(code, callback_url)
+        raise "Please ensure you've defined the client_id" if @client_id.nil?
+        raise "Please ensure you've defined the client_secret" if @client_secret.nil?
+        raise "No code was provided" if code.nil?
+        raise "Invalid callback url" if (callback_url.nil? or callback_url.scan(/http\:\/\//).empty?)
+
+        query = {
+          :client_id => @client_id,
+          :client_secret => @client_secret,
+          :grant_type => 'authorization_code',
+          :redirect_uri => callback_url,
+          :code => code
+        }
+        request = self.class.get("/access_token", {:query => query})
+        if request.code == 200
+          request.parsed_response['access_token']
+        else
+          raise Errors::OAuthError, request.parsed_response['error']
+        end
+      end
+
+      %w(campaigns specials venue_groups venues).each do |endpoint|
+        define_method "#{endpoint}" do
+          elem = camel_case(endpoint)
+          Foursquare::Merchant.module_eval("#{elem}").new(self)
+        end
+      end
+    end
+
+  end
+end