Add documentation + online tests

README.md

@@ -1,4 +1,4 @@
-# Sendgrid::Api
+# Sendgrid::API
 
 [![Build Status](https://secure.travis-ci.org/renatosnrg/sendgrid-api.png?branch=master)][gem]
 [![Code Climate](https://codeclimate.com/github/renatosnrg/sendgrid-api.png)][codeclimate]
@@ -10,6 +10,16 @@
 
 A Ruby interface to the SendGrid API.
 
+## API Coverage
+
+The SendGrid API is being covered on demand. The next APIs to be supported are the complete [Marketing Email API](http://sendgrid.com/docs/API_Reference/Marketing_Emails_API/index.html) and [Mail](http://sendgrid.com/docs/API_Reference/Web_API/mail.html) (Web API).
+
+Check which SendGrid APIs are currently being covered by this gem:
+
+[https://github.com/renatosnrg/sendgrid-api/wiki/SendGrid-API-Coverage][coverage]
+
+[coverage]: https://github.com/renatosnrg/sendgrid-api/wiki/SendGrid-API-Coverage
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -24,14 +34,40 @@ Or install it yourself as:
 
     $ gem install sendgrid-api
 
-## Usage
+## Configuration
+
+```ruby
+client = Sendgrid::API::Client.new('YOUR_USER', 'YOUR_KEY')
+```
+
+## Usage Examples
 
-TODO
+**Get your SendGrid Profile**
+
+```ruby
+profile = client.profile.get
+```
+
+**Modify your SendGrid Profile**
+
+```ruby
+profile = Sendgrid::API::Entities::Profile.new(:first_name => 'Your first name',
+                                               :last_name => 'Your last name')
+response = client.profile.set(profile)
+```
+
+**Get Advanced Statistics**
+
+```ruby
+stats = client.stats.advanced(:start_date => '2013-01-01', :data_type => 'global')
+```
 
 ## Contributing
 
+If you want to contribute to cover more APIs or improve something already implemented, follow these steps:
+
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
+3. Commit your changes - do not forget tests (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request

Rakefile

@@ -1,7 +1,9 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec, :tag) do |t, task_args|
+  t.rspec_opts = "--tag #{task_args[:tag]}" if task_args[:tag]
+end
 
 task :default => :spec
 task :test => :spec

lib/sendgrid/api/web/profile.rb

@@ -16,16 +16,16 @@ class Services < Sendgrid::API::Service
           # View your SendGrid profile
           #
           # @see http://sendgrid.com/docs/API_Reference/Web_API/profile.html
-          # @return profile [Profile] A Web::Profile object.
+          # @return profile [Profile] An Entities::Profile object.
           def get
             perform_request(Entities::Profile, 'profile.get.json').first
           end
 
           # Update your SendGrid profile
           #
           # @see http://sendgrid.com/docs/API_Reference/Web_API/profile.html#-set
-          # @param profile [Profile] A Web::Profile object.
-          # @return response [Response] A Response object.
+          # @param profile [Profile] An Entities::Profile object.
+          # @return response [Response] An Entities::Response object.
           def set(profile)
             perform_request(Entities::Response, 'profile.set.json', profile.as_json)
           end

lib/sendgrid/api/web/stats.rb

@@ -15,7 +15,15 @@ class Services < Sendgrid::API::Service
           # Get Advanced Statistics
           #
           # @see http://sendgrid.com/docs/API_Reference/Web_API/Statistics/statistics_advanced.html
-          # @return stats [Stats] An array of Web::Stats object.
+          # @param options [Hash] A customizable set of options.
+          # @option options [String] :data_type One of the following: browsers, clients, devices, geo, global, isps. Required.
+          # @option options [Date] :start_date Date format is based on aggregated_by value (default is yyyy-mm-dd). Required.
+          # @option options [Date] :end_date Date format is based on aggregated_by value (default is yyyy-mm-dd).
+          # @option options [String] :metric One of the following (default is all): open, click, unique_open, unique_click, processed, delivered, drop, bounce, deferred, spamreport, blocked, all.
+          # @option options [String] :category Return stats for the given category.
+          # @option options [String] :aggregated_by Aggregate the data by the given period (default is day): day, week or month.
+          # @option options [String] :country Get stats for each region/state for the given country. Only US (United States) and CA (Canada) is supported at this time.
+          # @return stats [Stats] An array of Entities::Stats object.
           def advanced(params = {})
             perform_request(Entities::Stats, 'stats.getAdvanced.json', params)
           end

spec/sendgrid/api/web/profile_spec.rb

@@ -82,6 +82,43 @@ module Profile
             end
           end
 
+          describe 'online tests', :online => true do
+            include_examples 'online tests'
+
+            context 'when credentials are valid' do
+              let(:resource) { REST::Resource.new(env_user, env_key) }
+
+              describe '#get' do
+                it 'should get profile' do
+                  subject.get.should be_instance_of(Entities::Profile)
+                end
+              end
+
+              describe '#set' do
+                it 'should update profile' do
+                  profile = subject.get
+                  subject.set(profile).success?.should be_true
+                end
+              end
+            end
+
+            context 'when credentials are invalid' do
+              describe '#get' do
+                it 'should raise error' do
+                  expect { subject.get }.to raise_error(REST::Errors::Unauthorized)
+                end
+              end
+
+              describe '#set' do
+                let(:profile) { Entities::Profile.new(:first_name => 'Brian', :last_name => 'O\'Neill') }
+
+                it 'should raise error' do
+                  expect { subject.set(profile) }.to raise_error(REST::Errors::Unauthorized)
+                end
+              end
+            end
+          end
+
         end
       end
     end

spec/sendgrid/api/web/stats_spec.rb

@@ -60,6 +60,39 @@ module Stats
             end
           end
 
+          describe 'online tests', :online => true do
+            include_examples 'online tests'
+
+            context 'when credentials are valid' do
+              let(:resource) { REST::Resource.new(env_user, env_key) }
+
+              describe '#advanced' do
+                context 'with required params' do
+                  # 90 days from now
+                  let(:start_date) { (Time.now - (90*24*60*60)).strftime("%Y-%m-%d") }
+
+                  it 'should get stats' do
+                    subject.advanced(:start_date => start_date, :data_type => :global).should_not be_empty
+                  end
+                end
+
+                context 'without required params' do
+                  it 'should raise error' do
+                    expect { subject.advanced }.to raise_error(REST::Errors::BadRequest)
+                  end
+                end
+              end
+            end
+
+            context 'when credentials are invalid' do
+              describe '#advanced' do
+                it 'should raise error' do
+                  expect { subject.advanced }.to raise_error(REST::Errors::Forbidden)
+                end
+              end
+            end
+          end
+
         end
       end
     end

spec/spec_helper.rb

@@ -14,42 +14,10 @@
 require 'rspec'
 require 'webmock/rspec'
 
-WebMock.disable_net_connect!(:allow => 'coveralls.io')
+Dir["./spec/support/**/*.rb"].sort.each { |f| require f }
 
 RSpec.configure do |config|
+  config.filter_run_excluding :online => true unless ENV['ALL']
 end
 
-module Sendgrid
-  class Mock
-    include WebMock::API
-
-    def initialize(user, key)
-      @user = user
-      @key = key
-    end
-
-    def stub_post(path, params = {})
-      stub_request(:post, Sendgrid::API::REST::Resource::ENDPOINT + '/' + path).
-        with(:body => params.merge(authentication_params))
-    end
-
-    def a_post(path, params = {})
-      a_request(:post, Sendgrid::API::REST::Resource::ENDPOINT + '/' + path).
-        with(:body => params.merge(authentication_params))
-    end
-
-    private
-
-    def authentication_params
-      { :api_key => @key, :api_user => @user }
-    end
-  end
-end
-
-def fixture_path
-  File.expand_path("../fixtures", __FILE__)
-end
-
-def fixture(file)
-  File.new(fixture_path + '/' + file)
-end
+disable_http

spec/support/helpers.rb

@@ -0,0 +1,15 @@
+def fixture_path
+  File.expand_path("../../fixtures", __FILE__)
+end
+
+def fixture(file)
+  File.new(fixture_path + '/' + file)
+end
+
+def enable_http
+  WebMock.allow_net_connect!
+end
+
+def disable_http
+  WebMock.disable_net_connect!(:allow => 'coveralls.io')
+end

spec/support/mock.rb

@@ -0,0 +1,26 @@
+module Sendgrid
+  class Mock
+    include WebMock::API
+
+    def initialize(user, key)
+      @user = user
+      @key = key
+    end
+
+    def stub_post(path, params = {})
+      stub_request(:post, Sendgrid::API::REST::Resource::ENDPOINT + '/' + path).
+        with(:body => params.merge(authentication_params))
+    end
+
+    def a_post(path, params = {})
+      a_request(:post, Sendgrid::API::REST::Resource::ENDPOINT + '/' + path).
+        with(:body => params.merge(authentication_params))
+    end
+
+    private
+
+    def authentication_params
+      { :api_key => @key, :api_user => @user }
+    end
+  end
+end

spec/support/shared_examples.rb

@@ -0,0 +1,11 @@
+shared_examples 'online tests' do
+  before do
+    enable_http
+  end
+  after do
+    disable_http
+  end
+
+  let(:env_user)  { ENV['SENDGRID_USER'] }
+  let(:env_key)   { ENV['SENDGRID_KEY'] }
+end