aweber 1.0.0

data/Gemfile

@@ -0,0 +1,9 @@
+source :rubygems
+gem "oauth"
+gem "json_pure"
+
+group :development do
+  gem "fakeweb"
+  gem "rspec", "2.0.0.beta.22"
+  gem "yard",  "~> 0.6.1"
+end

data/Gemfile.lock

@@ -0,0 +1,28 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    fakeweb (1.3.0)
+    json_pure (1.4.6)
+    oauth (0.4.4)
+    rspec (2.0.0.beta.22)
+      rspec-core (= 2.0.0.beta.22)
+      rspec-expectations (= 2.0.0.beta.22)
+      rspec-mocks (= 2.0.0.beta.22)
+    rspec-core (2.0.0.beta.22)
+    rspec-expectations (2.0.0.beta.22)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.0.beta.22)
+      rspec-core (= 2.0.0.beta.22)
+      rspec-expectations (= 2.0.0.beta.22)
+    yard (0.6.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  fakeweb
+  json_pure
+  oauth
+  rspec (= 2.0.0.beta.22)
+  yard (~> 0.6.1)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 AWeber Communications, Inc.
+
+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.textile

@@ -0,0 +1,45 @@
+h1. AWeber API Gem
+
+Official AWeber API gem.
+
+h2. Installation
+
+* @gem install aweber@
+
+h2. Quick Start
+
+First, go to "http://labs.aweber.com":http://labs.aweber.com and sign up for a free AWeber Labs account. This is how you register apps and get OAuth keys.
+
+bc. # Register an app and use it's Consumer key and secret:
+oauth = AWeber::OAuth.new("consumer_key", "consumer_secret")
+# Go to the URL the following outputs.
+oauth.request_token.authorize_url 
+# Authorize your account and copy the verification code.
+oauth.authorize_with_verifier("verification_code")
+aweber  = AWeber::Base.new(oauth)
+account = aweber.account
+account.lists # Start getting data
+
+Take a look at "examples":http://github.com/aweber/aweber-ruby/tree/master/examples/ for more examples.
+
+h2. Getting Data
+
+Every piece of data from AWeber's API stems from an Account object. From there you access associated resources in the same way you would an ActiveRecord accosication:
+
+bc. account.lists #=> #<AWeber::Collection(AWeber::Resource::List)>
+account.lists[1] #=> #<AWeber::Resource::List>
+account.lists[1].web_forms #=> #<AWeber::Collection(AWeber::Resource::WebForm)>
+
+h2. Note on Patches/Pull Requests
+ 
+* 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 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.
+
+h2. Copyright
+
+Copyright (c) 2010 AWeber Communications, Inc. See LICENSE for more detail.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |s|
+  s.rspec_opts = ["--color"]
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new(:yard)
+
+task :default => :spec

data/aweber.gemspec

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |s|
+  s.name         = "aweber"
+  s.version      = "1.0.0"
+  s.platform     = Gem::Platform::RUBY
+  s.summary      = "Ruby interface to AWeber's API"
+  s.description  = "Ruby interface to AWeber's API"
+  
+  s.author       = "AWeber Communications, Inc."
+  s.email        = "help@aweber.com"
+  s.homepage     = "http://github.com/aweber/AWeber-API-Ruby-Library"
+  
+  s.require_path = "lib"
+  s.files        = [
+    "aweber.gemspec",
+    "examples/with_access_token.rb",
+    "examples/your_account.rb",
+    "Gemfile",
+    "Gemfile.lock",
+    "lib/aweber.rb",
+    "lib/aweber/base.rb",
+    "lib/aweber/collection.rb",
+    "lib/aweber/oauth.rb",
+    "lib/aweber/resource.rb",
+    "lib/aweber/resources.rb",
+    "lib/aweber/resources/account.rb",
+    "lib/aweber/resources/broadcast.rb",
+    "lib/aweber/resources/click.rb",
+    "lib/aweber/resources/followup.rb",
+    "lib/aweber/resources/integration.rb",
+    "lib/aweber/resources/link.rb",
+    "lib/aweber/resources/list.rb",
+    "lib/aweber/resources/message.rb",
+    "lib/aweber/resources/open.rb",
+    "lib/aweber/resources/subscriber.rb",
+    "lib/aweber/resources/tracked_event.rb",
+    "lib/aweber/resources/web_form.rb",
+    "lib/aweber/resources/web_form_split_test.rb",
+    "lib/aweber/resources/web_form_split_test_component.rb",
+    "LICENSE",
+    "Rakefile",
+    "README.textile",
+  ]
+  
+  s.test_files   = Dir["spec/**/*"]
+  s.extra_rdoc_files = ["LICENSE", "README.textile"]
+
+  s.add_dependency "oauth"
+  s.add_dependency "json_pure"
+  
+  s.add_development_dependency "fakeweb"
+  s.add_development_dependency "rspec", ">= 2.0.0"
+  s.add_development_dependency "yard", "~> 0.6.1"
+end
+

data/examples/with_access_token.rb

@@ -0,0 +1,17 @@
+# Getting started with saved Access Tokens
+# ========================================
+@oauth = AWeber::OAuth.new("consumer_key", "consumer_secret")
+
+# Use your saved Access Token token and secret to authorize.
+#
+# This is also how you'd authorize your users' accounts after
+# they've authorized your app to access their data for the
+# first time.
+@oauth.authorize_with_access("token", "secret")
+
+# Go on your merry way.
+@aweber = AWeber::Base.new(@oauth)
+@account = @aweber.account
+@account.lists
+@account.lists[1].web_forms
+# etc

data/examples/your_account.rb

@@ -0,0 +1,26 @@
+# Getting started with your own AWeber Account
+# ============================================
+
+# First, go to http://labs.aweber.com, get a free AWeber Labs
+# account and create an App.
+@oauth = AWeber::OAuth.new("consumer_key", "consumer_secret")
+
+# Go to URL outputed by the following, authorize your account
+# and copy the verification code
+@oauth.request_token.authorize_url
+@oauth.authorize_with_verifier("verification_code")
+
+# Save your Access Tokens for later use, you won't need
+# to do all this once you have it. Check out
+# with_access_tokens.rb for an example of this.
+#
+# DATASTORE << @oauth.access_token.token
+# DATASTORE << @oauth.access_token.secret
+
+@aweber = AWeber::Base.new(@oauth)
+# An account is the root resource for all AWeber data
+@account = @aweber.account
+
+@account.lists
+@account.lists[1].web_forms
+# etc

data/lib/aweber.rb

@@ -0,0 +1,67 @@
+require "forwardable"
+require "oauth"
+require "json/pure"
+
+module AWeber
+  API_VERSION  = "1.0".freeze
+  AUTH_VERSION = "1.0".freeze
+  
+  # Used for +has_many+ and +has_one+ relationships.
+  # 
+  INFLECTIONS  = { 
+    :accounts             => :Account,
+    :clicks               => :Click,
+    :links                => :Link,
+    :lists                => :List,
+    :messages             => :Message,
+    :opens                => :Open,
+    :subscribers          => :Subscriber,
+    :tracked_events       => :TrackedEvent,
+    :integrations         => :Integration,
+    :web_forms            => :WebForm,
+    :components           => :WebFormSplitTestComponent,
+    :web_form_split_tests => :WebFormSplitTest,
+    :last_followup_sents  => :Followup
+  }
+  
+  class << self
+    # @param [String] Base URL of the API server
+    #
+    attr_accessor :api_endpoint
+    
+    # @param [String] Base URL of the Auth server
+    #
+    attr_accessor :auth_endpoint
+    
+    def api_url
+      File.join api_endpoint, API_VERSION
+    end
+    
+    def auth_url
+      File.join auth_endpoint, AUTH_VERSION
+    end
+    
+    # Retrieves the Resource class based on the 
+    # +INFLECTIONS+ map and +name+.
+    #
+    # @param [Symbol] name Collection name
+    #
+    def get_class(name)
+      Resources.const_get(INFLECTIONS[name])
+    end
+  end
+  
+  @api_endpoint  = "https://api.aweber.com"
+  @auth_endpoint = "https://auth.aweber.com"
+  
+  class OAuthError < Exception; end
+  class NotFoundError < Exception; end
+  class UnknownRequestError < Exception; end
+end
+
+$LOAD_PATH << File.dirname(__FILE__) unless $LOAD_PATH.include?(File.dirname(__FILE__))
+require "aweber/oauth"
+require "aweber/base"
+require "aweber/resource"
+require "aweber/resources"
+require "aweber/collection"

data/lib/aweber/base.rb

@@ -0,0 +1,49 @@
+module AWeber
+  class Base
+
+    def initialize(oauth)
+      @oauth = oauth
+    end
+
+    def account
+      accounts.first.last
+    end
+
+  private
+
+    def get(uri)
+      response = oauth.get(expand(uri))
+      handle_errors(response, uri)
+      parse(response) if response
+    end
+    
+    def handle_errors(response, uri)
+      if response.is_a? Net::HTTPNotFound
+        raise NotFoundError, "Invalid resource uri.", caller
+      elsif response && response.body == "NotAuthorizedError"
+        raise OAuthError, "Could not authorize OAuth credentials.", caller
+      end
+    end
+
+    def accounts
+      @accounts ||= Collection.new(self, Resources::Account, get("/accounts"))
+    end
+
+    def expand(uri)
+      parsed = URI.parse(uri)
+      url = []
+      url << AWeber.api_endpoint unless parsed.host
+      url << API_VERSION unless parsed.path.include? API_VERSION
+      url << uri
+      File.join(*url)
+    end
+
+    def parse(response)
+      JSON.parse(response.body)
+    end
+
+    def oauth
+      @oauth
+    end
+  end
+end

data/lib/aweber/collection.rb

@@ -0,0 +1,110 @@
+module AWeber
+  # Collection objects are groups of Resources. Collections imitate
+  # regular Hashes in most ways. You can access Resource by +id+ via the
+  # +[]+ method.
+  #
+  #    lists    #=> #<AWeber::Collection ...>
+  #    lists[1] #=> #<AWeber::Resources::List @id=1 ...>
+  #
+  # Also like Hashes, you can iterate over all of it's entries
+  #
+  #    lists.each { |id, list| puts list.name }
+  #
+  # Collections support dynamic +find_by_*+ methods, where +*+ is an
+  # attribute and the first and only parameter is the value.
+  #
+  #    lists.find_by_name("testlist")
+  #    #=> #<AWeber::Resources::List @id=123, @name="testlist" ...>
+  #
+  # +find_by_*+ methods will also return a Hash of entries if more than 
+  # one matches the criteria. The hash will be keyed by resource ID.
+  #
+  #    messages.find_by_total_opens(0)
+  #    #=> { "45697" => #<Message>, "12345" => #<Message> }
+  #
+  # Collections are paginated in groups of 20.
+  #
+  class Collection < Resource
+    include Enumerable
+
+    attr_reader :entries
+    attr_reader :next_collection_link
+    attr_reader :prev_collection_link
+    attr_reader :resource_type_link
+    attr_reader :total_size
+
+    alias_method :size,   :total_size
+    alias_method :length, :total_size
+
+    # @param [AWeber::Base] client    Instance of AWeber::Base
+    # @param [Class] klass            Class to create entries of
+    # @param [Hash]  data             JSON decoded response data Hash
+    #
+    def initialize(client, klass, data={})
+      super client, data
+      @client  = client
+      @klass   = klass
+      @entries = {}
+      create_entries(data["entries"])
+      @_entries = @entries.to_a
+    end
+
+    def [](id)
+      @entries[id] ||= fetch_entry(id)
+    end
+
+    def each
+      (1..@total_size).each { |n| yield get_entry(n) }
+    end
+
+    def inspect
+      "#<AW::Collection(#{@klass.to_s}) size=\"#{size}\">"
+    end
+
+  private
+
+    def create_entries(entries)
+      entries.each { |entry| @entries[entry["id"]] = @klass.new(client, entry) }
+    end
+
+    def get_entry(n)
+      @_entries += fetch_next_group if needs_next_group?(n)
+      @_entries[n-1]
+    end
+
+    def fetch_entry(id)
+      @klass.new(client, get(File.join(base_path, id.to_s)))
+    end
+
+    def fetch_next_group(amount=20)
+      path = "#{ base_path }?ws.start=#{ @_entries.size }&ws.size=#{ amount }"
+      self.class.new(client, @klass, get(path)).entries.to_a
+    end
+
+    def needs_next_group?(current_index)
+      current_index == @_entries.size && current_index != @total_size
+    end
+
+    def base_path
+      URI.parse(@next_collection_link).path
+    end
+
+    def find_by(_attr, *args)
+      matches = select { |id, e| e.send(_attr) == args.first }
+      matches = matches.first.last if matches.size == 1
+      matches
+    end
+
+    def method_missing(method, *args)
+      method.to_s.scan /^find_by_(.+)/ do |_attr|
+        return find_by(_attr.first, *args)
+      end
+      super
+    end
+
+    def client
+      @client
+    end
+
+  end
+end