twelve 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+README (Autosaved)
+Gemfile.lock
+spec/.access_token
+spec/responses/
+spec/.gauge_id

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Jonathan Hoyt
+
+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,220 @@
+Twelve (gauge)
+==================
+
+This is an unofficial ruby client for the [Gauges API](http://get.gaug.es/documentation/api/). The end goal is a complete, simple, and intuitive ruby API for all things Gauges.
+
+Usage
+-----
+
+Instantiate the client:
+
+    access_token = "abcd1234"
+    bfg = Twelve.new(access_token)
+
+### Your Information
+
+Get your information:
+
+    bfg.me
+
+Update your information:
+
+    bfg.me({
+      :first_name => "John",
+      :last_name => "Doe"
+    })
+
+### API Clients
+
+Get your API clients:
+
+    bfg.clients
+
+Create an API client:
+
+    bfg.clients.create(:description => "12 Gauge")
+
+Delete an API client:
+
+    client_id = 'abcd1234'
+    bfg.clients(client_id).destroy
+
+### Gauges
+
+Get your gauges:
+
+    bfg.gauges
+
+Create a gauge:
+
+    bfg.gauges.create({
+      :title => 'theprogrammingbutler.com',
+      :tz => 'Eastern Time (US & Canada)'
+    })
+
+Get a specific gauge:
+
+    gauge_id = 'abcd1234'
+    bfg.gauges(gauge_id)
+
+Update a gauge:
+
+    bfg.gauges('abcd1234', {
+      :title => 'Go get your guns'
+    })
+
+Delete a gauge:
+
+    bfg.gauges('abcd1234').destroy
+
+### Sharing
+
+List who a gauge is shared with:
+
+    bfg.gauges('abcd1234').shares
+
+Share a gauge:
+
+    bfg.gauges('abcd1234').share({:email => 'john@doe.com'})
+
+Un-share a gauge:
+
+    user_id = '4321dcba'
+    bfg.gauges('abcd1234').unshare(user_id)
+
+### Content
+
+Get today's top content for a gauge:
+
+    bfg.gauges('abcd1234').content
+
+Get the second page of top content for a gauge:
+
+    bfg.gauges('abcd1234').content(:page => 2)
+
+Get top content for a specific date of a gauge:
+
+    bfg.gauges('abcd1234').content('2011-12-9')
+
+Get the second page for a specific date:
+
+    bfg.gauges('abcd1234').content('2011-12-9', :page => 2)
+
+### Referrers
+
+Get today's referrers for a gauge:
+
+    bfg.gauges('abcd1234').referrers
+
+Get the second page of referrers for a gauge:
+
+    bfg.gauges('abcd1234').referrers(:page => 2)
+
+Get referrers for a specific date of a gauge:
+
+    bfg.gauges('abcd1234').referrers('2011-12-9')
+
+Get the second page for a specific date:
+
+    bfg.gauges('abcd1234').referrers('2011-12-9', :page => 2)
+
+### Trafic
+
+Get this month's traffic for a gauge:
+
+    bfg.gauges('abcd1234').traffic
+
+Get a specific month's traffic:
+
+    bfg.gauges('abcd1234').traffic('2011-10-1')
+
+### Resolutions
+
+Get this month's screen sizes for a gauge:
+
+    bfg.gauges('abcd1234').traffic
+
+Get a specific month's screen sizes:
+
+    bfg.gauges('abcd1234').traffic('2011-10-1')
+
+### Technology
+
+Get browsers and platforms for a gauge:
+
+    bfg.gauges('abcd1234').technology
+
+Get a specific month's technology:
+
+    bfg.gauges('abcd1234').technology('2011-10-1')
+
+### Search Terms
+
+Get today's search terms for a gauge:
+
+    bfg.gauges('abcd1234').terms
+
+Get the second page of search terms for a gauge:
+
+    bfg.gauges('abcd1234').terms(:page => 2)
+
+Get search terms for a specific date of a gauge:
+
+    bfg.gauges('abcd1234').terms('2011-12-9')
+
+Get the second page for a specific date:
+
+    bfg.gauges('abcd1234').terms('2011-12-9', :page => 2)
+
+### Search Engines
+
+Get search engines for a gauge:
+
+    bfg.gauges('abcd1234').engines
+
+Get a specific month's search engines:
+
+    bfg.gauges('abcd1234').engines('2011-10-1')
+
+### Locations
+
+Get this month's locations for a gauge:
+
+    bfg.gauges('abcd1234').locations
+
+Get a specific month's locations:
+
+    bfg.gauges('abcd1234').locations('2011-10-1')
+
+Testing
+-------
+
+The test suite uses [VCR](https://github.com/myronmarston/vcr) to cache actual requests to the Gauges API in a directory called responses in the spec directory. In order for VCR to make and cache the actual calls to the Gauges API you will need to provide your Gauges access_token by placing it in a file named .access_token in the spec directory.
+
+To run the tests for content, referrers, traffic, resolutions, technology, search terms, search engines, and locations, you will also need to have an id for a gauge that has been collecting data for at least two days. You place this gauge id in spec/.gauge_id and spec_helper will use it.
+
+This file is ignored by git (see .gitignore) so you can commit any changes you make to the gem without having to worry about your token being released into the wild.
+
+Now run the test suite:
+
+    bundle
+    bundle exec rake
+
+CONTRIBUTE
+----------
+
+If you'd like to hack on Twelve, start by forking the repo on GitHub:
+
+https://github.com/jonmagic/twelve
+
+The best way to get your changes merged back into core is as follows:
+
+1. Clone down your fork
+1. Create a thoughtfully named topic branch to contain your change
+1. Hack away
+1. Add tests and make sure everything still passes by running `bundle exec rake`
+1. If you are adding new functionality, document it in the README
+1. Do not change the version number, we will do that on our end
+1. If necessary, rebase your commits into logical chunks, without errors
+1. Push the branch up to GitHub
+1. Send a pull request for your branch

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+desc "Run the specs"
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/lib/twelve.rb

@@ -0,0 +1,32 @@
+# encoding: UTF-8
+require 'twelve/version'
+require 'twelve/connection'
+require 'twelve/resource_proxy'
+require 'twelve/api/me'
+require 'twelve/api/clients'
+require 'twelve/api/gauges/shares'
+require 'twelve/api/gauges/content'
+require 'twelve/api/gauges/referrers'
+require 'twelve/api/gauges/traffic'
+require 'twelve/api/gauges/resolutions'
+require 'twelve/api/gauges/technology'
+require 'twelve/api/gauges/terms'
+require 'twelve/api/gauges/engines'
+require 'twelve/api/gauges/locations'
+require 'twelve/api/gauges'
+
+class Twelve
+  attr_reader :connection
+
+  include Twelve::API::Me
+  include Twelve::API::Clients
+  include Twelve::API::Gauges
+
+  # Instantiates Twelve, requires an access_token
+  #
+  # Access_token - String of the access_token
+  #
+  def initialize(access_token=nil)
+    @connection = Twelve::Connection.new(access_token)
+  end
+end

data/lib/twelve/api/clients.rb

@@ -0,0 +1,55 @@
+class Twelve
+
+  # API module encapsulates all of the API endpoints
+  #
+  module API
+
+    # The Clients module handles API Clients on Gauges
+    #
+    module Clients
+
+      # Clients::Proxy inherits from Twelve::Proxy and
+      # enables defining methods on the proxy object
+      #
+      class Proxy < ::Twelve::ResourceProxy
+
+        # Creates an API client
+        #
+        # attributes - Hash of attributes
+        #
+        # Returns json
+        #
+        def create(attributes)
+          connection.post(path_prefix, attributes).body['client']
+        end
+
+        # Deletes an API client
+        #
+        # key - String of key
+        #
+        # Returns json
+        #
+        def destroy
+          connection.delete(path_prefix).body['client']
+        end
+
+        # Get API clients
+        #
+        # Returns json
+        #
+        def subject
+          @subject ||= connection.get(path_prefix).body['clients']
+        end
+      end
+
+      # Get API clients
+      #
+      # Returns json
+      #
+      def clients(id=nil)
+        path_prefix = id ? "/clients/#{id}" : '/clients'
+        Proxy.new(connection, path_prefix)
+      end
+    end
+  end
+end

data/lib/twelve/api/gauges.rb

@@ -0,0 +1,67 @@
+class Twelve
+
+  # API module encapsulates all of the API endpoints
+  #
+  module API
+
+    # The Gauges module handles Gauges on Gauges
+    #
+    module Gauges
+
+      # Gauges::Proxy inherits from Twelve::Proxy and
+      # enables defining methods on the proxy object
+      #
+      class Proxy < ::Twelve::ResourceProxy
+        include Twelve::API::Gauges::Shares
+        include Twelve::API::Gauges::Content
+        include Twelve::API::Gauges::Referrers
+        include Twelve::API::Gauges::Traffic
+        include Twelve::API::Gauges::Resolutions
+        include Twelve::API::Gauges::Technology
+        include Twelve::API::Gauges::Terms
+        include Twelve::API::Gauges::Engines
+        include Twelve::API::Gauges::Locations
+
+        # Creates a gauge
+        #
+        # attributes - Hash of attributes
+        #
+        # Returns json
+        #
+        def create(attributes)
+          connection.post(path_prefix, attributes).body['gauge']
+        end
+
+        # Deletes a gauge
+        #
+        # Returns json
+        #
+        def destroy
+          connection.delete(path_prefix).body['gauge']
+        end
+
+        # Get gauges, gauge, or update gauge
+        #
+        # Returns json
+        #
+        def subject
+          response = if attributes
+            connection.put(path_prefix, attributes).body
+          else
+            connection.get(path_prefix).body
+          end
+          @subject ||= path_prefix == '/gauges' ? response['gauges'] : response['gauge']
+        end
+      end
+
+      # Get, Create, Update, and Delete Gauges
+      #
+      # Returns json
+      #
+      def gauges(id=nil, attributes=nil)
+        path_prefix = id ? "/gauges/#{id}" : '/gauges'
+        Proxy.new(connection, path_prefix, attributes)
+      end
+    end
+  end
+end

data/lib/twelve/api/gauges/content.rb

@@ -0,0 +1,36 @@
+class Twelve
+
+  # API module encapsulates all of the API endpoints
+  #
+  module API
+
+    # The Gauges module handles Gauges on Gauges
+    #
+    module Gauges
+
+      # The Content module handles top content
+      #
+      module Content
+
+        # Returns top content for a gauge
+        #
+        # *args - Date string & options hash
+        #
+        # Returns json
+        #
+        def content(*args)
+          attributes = {}
+
+          connection.get do |request|
+            request.url "#{path_prefix}/content"
+
+            args.each do |arg|
+              request.params['page'] = arg[:page].to_s if arg.is_a?(Hash) && arg.has_key?(:page)
+              request.params['date'] = arg if arg.is_a?(String)
+            end
+          end.body
+        end
+      end
+    end
+  end
+end