pew_pew 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.rvmrc
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+bin
+coverage
+doc
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Tyler Hunt
+
+MIT License
+
+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,84 @@
+# Pew Pew
+
+A Ruby client library for using the [Mailgun] web service.
+
+[mailgun]: https://mailgun.net/
+
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+``` ruby
+gem 'pew_pew'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pew_pew
+
+
+## Configuration
+
+You must have a valid API key to use the Mailgun API. If you don't yet have
+one, you can [sign up here][api-key].
+
+[api-key]: http://www.mailgun.net/signup
+
+You can use the following method to configure your API key and domain:
+
+``` ruby
+PewPew.configure do |config|
+  config.api_key = ENV['MAILGUN_API_KEY']
+  config.domain = ENV['MAILGUN_DOMAIN'] # optional
+end
+```
+
+If you'd like to use multiple instances of the API with different keys, you can
+instantiate `PewPew::Client` directly and treat those instances the same as you
+would the `PewPew` module:
+
+``` ruby
+pew_pew = PewPew::Client.new
+
+pew_pew.configure do |config|
+  config.api_key = ENV['MAILGUN_API_KEY']
+  config.domain = ENV['MAILGUN_DOMAIN'] # optional
+end
+```
+
+
+## Usage
+
+Once the API key has been configured, resources can be called on the `PewPew`
+module directly or off your client instances:
+
+``` ruby
+PewPew.messages.send_email(
+  to: 'to@example.com',
+  from: 'from@example.com',
+  subject: 'Test',
+  text: 'This is a test message.'
+)
+```
+
+For resources that require a domain, you may pass it as an option when calling
+the resource. If a domain has been configured, it will be used as the default.
+
+``` ruby
+PewPew.stats.all # uses the configured domain
+PewPew.stats(domain: 'example.com').all # uses example.com
+```
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature.'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,3 @@
+#!/usr/bin/env rake
+
+require 'bundler/gem_tasks'

data/lib/pew_pew.rb

@@ -0,0 +1,32 @@
+require 'pew_pew/version'
+require 'relax'
+
+module PewPew
+  extend Relax::Delegator[:client]
+
+  autoload :Client, 'pew_pew/client'
+  autoload :Config, 'pew_pew/config'
+  autoload :Domain, 'pew_pew/domain'
+  autoload :Resource, 'pew_pew/resource'
+  autoload :Response, 'pew_pew/response'
+
+  module Resources
+    autoload :Bounces, 'pew_pew/resources/bounces'
+    autoload :Campaigns, 'pew_pew/resources/campaigns'
+    autoload :Complaints, 'pew_pew/resources/complaints'
+    autoload :Lists, 'pew_pew/resources/lists'
+    autoload :Logs, 'pew_pew/resources/logs'
+    autoload :Mailboxes, 'pew_pew/resources/mailboxes'
+    autoload :Messages, 'pew_pew/resources/messages'
+    autoload :Routes, 'pew_pew/resources/routes'
+    autoload :Stats, 'pew_pew/resources/stats'
+    autoload :Unsubscribes, 'pew_pew/resources/unsubscribes'
+  end
+
+  # @return a memoized instance of the client
+  # @!visibility private
+  def self.client
+    @client ||= Client.new
+  end
+  private_class_method :client
+end

data/lib/pew_pew/client.rb

@@ -0,0 +1,90 @@
+module PewPew
+  class Client
+    include Relax::Client
+
+    # Returns a new client instance and configures its default values.
+    def initialize
+      config.base_uri = Config::BASE_URI
+      config.user_agent = Config::USER_AGENT
+      config.extend(Config)
+    end
+
+    # Builds a new instance of the bounces resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Bounces> an instance of the bounces resource
+    def bounces(options={})
+      Resources::Bounces.new(self, options)
+    end
+
+    # Builds a new instance of the campaigns resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Campaigns> an instance of the complaints resource
+    def campaigns(options={})
+      Resources::Campaigns.new(self, options)
+    end
+
+    # Builds a new instance of the complaints resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Complaints> an instance of the complaints resource
+    def complaints(options={})
+      Resources::Complaints.new(self, options)
+    end
+
+    # Builds a new instance of the lists resource.
+    #
+    # @return <Resources::Lists> an instance of the lists resource
+    def lists
+      Resources::Lists.new(self)
+    end
+
+    # Builds a new instance of the logs resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Logs> an instance of the logs resource
+    def logs(options={})
+      Resources::Logs.new(self, options)
+    end
+
+    # Builds a new instance of the mailboxes resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Mailboxes> an instance of the mailboxes resource
+    def mailboxes(options={})
+      Resources::Mailboxes.new(self, options)
+    end
+
+    # Builds a new instance of the messages resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Messages> an instance of the messages resource
+    def messages(options={})
+      Resources::Messages.new(self, options)
+    end
+
+    # Builds a new instance of the routes resource.
+    #
+    # @return <Resources::Routes> an instance of the routes resource
+    def routes
+      Resources::Routes.new(self)
+    end
+
+    # Builds a new instance of the stats resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Stats> an instance of the stats resource
+    def stats(options={})
+      Resources::Stats.new(self, options)
+    end
+
+    # Builds a new instance of the unsubscribes resource for the given domain.
+    #
+    # @option options [String] :domain the domain name
+    # @return <Resources::Unsubscribes> an instance of the unsubscribes resource
+    def unsubscribes(options={})
+      Resources::Unsubscribes.new(self, options)
+    end
+  end
+end

data/lib/pew_pew/config.rb

@@ -0,0 +1,15 @@
+module PewPew
+  module Config
+    BASE_URI = 'https://api.mailgun.net/v2'
+    USER_AGENT = "PewPew Ruby Gem #{PewPew::VERSION}"
+    USERNAME = 'api'
+
+    # The Mailgun API key used to authenticate requests.
+    # @return [String]
+    attr :api_key, true
+
+    # The default domain to use for resources that require a domain.
+    # @return [String]
+    attr :domain, true
+  end
+end

data/lib/pew_pew/domain.rb

@@ -0,0 +1,9 @@
+module PewPew
+  module Domain
+    def domain
+      @domain ||= @options[:domain] || config.domain
+    end
+    private :domain
+  end
+  private_constant :Domain
+end

data/lib/pew_pew/resource.rb

@@ -0,0 +1,52 @@
+require 'faraday_middleware'
+
+module PewPew
+  module Resource
+    include Relax::Resource
+
+    class ResponseDecorator < Faraday::Response::Middleware
+      def on_complete(env)
+        if env[:body].is_a?(Array)
+          items = env[:body]
+          env[:body] = Response.new(items: items, total_count: items.length)
+        end
+
+        env[:body].status = env[:status]
+      end
+    end
+
+    def get(*)
+      super.body
+    end
+    private :get
+
+    def post(*)
+      super.body
+    end
+    private :post
+
+    def put(*)
+      super.body
+    end
+    private :put
+
+    def delete(*)
+      super.body
+    end
+    private :delete
+
+    def connection
+      super do |builder|
+        builder.basic_auth(Config::USERNAME, config.api_key)
+
+        builder.use(ResponseDecorator)
+        builder.response(:mashify, mash_class: Response)
+        builder.response(:json)
+
+        builder.request(:multipart)
+        builder.request(:url_encoded)
+      end
+    end
+    private :connection
+  end
+end

data/lib/pew_pew/resources/bounces.rb

@@ -0,0 +1,41 @@
+module PewPew
+  module Resources
+    class Bounces
+      include Resource
+      include Domain
+
+      # Fetches all bounces.
+      #
+      # @return [Mash] the response body
+      def all
+        get("#{domain}/bounces")
+      end
+
+      # Fetch all bounces by address.
+      #
+      # @param address [String] the address to fetch bounces for
+      # @return [Mash] the response body
+      def find(address)
+        get("#{domain}/bounces/#{address}")
+      end
+
+      # Creates a new bounce.
+      #
+      # @option params [String] :address the email address to add
+      # @option params [String] :code error code (defaults to 550)
+      # @option params [String] :error error description (defaults to blank)
+      # @return [Mash] the response body
+      def create(params)
+        post("#{domain}/bounces", params)
+      end
+
+      # Removes existing bounces.
+      #
+      # @param address_or_id [String] the address to remove all the bounces for
+      # @return [Mash] the response body
+      def remove(address_or_id)
+        delete("#{domain}/bounces/#{address_or_id}")
+      end
+    end
+  end
+end

data/lib/pew_pew/resources/campaigns.rb

@@ -0,0 +1,141 @@
+module PewPew
+  module Resources
+    class Campaigns
+      include Resource
+      include Domain
+
+      # Fetches all campaigns for the domain.
+      #
+      # @return [Mash] the response body
+      def all
+        get("#{domain}/campaigns")
+      end
+
+      # Fetch a campaign by ID.
+      #
+      # @param id [String] the ID of the campaign to be fetched
+      # @return [Mash] the response body
+      def find(id)
+        get("#{domain}/campaigns/#{id}")
+      end
+
+      # Creates a new campaign.
+      #
+      # @option params [String] :name the name of the campaign
+      # @option params [String] :id optional campaign identifier (defaults to
+      #   an generated ID)
+      # @return [Mash] the response body
+      def create(params)
+        post("#{domain}/campaigns", params)
+      end
+
+      # Removes an existing campaign and all associated data.
+      #
+      # @param id [String] the ID of the campaign to be deleted
+      # @return [Mash] the response body
+      def remove(id)
+        delete("#{domain}/campaigns/#{id}")
+      end
+
+      # Fetch the events for a campaign, including clicks, opens, unsubscribes,
+      # bounces and complaints.
+      #
+      # @param id [String] a campaign ID
+      # @option params [String, Array<String>] :event optional event filter
+      #   (clicked, opened, unsubscribed, bounced, or complained)
+      # @option params [String] :address optional recipient email address
+      # @option params [String] :country optional two-letter country code
+      # @option params [String] :region optional region name or code
+      # @option params [Fixnum] :limit number of records to return (maximum 100)
+      # @option params [Fixnum] :page results page number
+      # @option params [Boolean] :count if true, return counts instead of
+      #   records
+      # @return [Mash] the response body
+      def events(id, params={})
+        get("#{domain}/campaigns/#{id}/events", params)
+      end
+
+      # Fetches a summary of the results for a given campaign, like numbers of
+      # clicks, opens, etc. Includes unique numbers (e.g. number of unique
+      # recipients who clicked) as well.
+      #
+      # @param id [String] a campaign ID
+      # @option params [String] :group_by optional grouping (domain or
+      #   daily_hour)
+      # @return [Mash] the response body
+      def stats(id, params={})
+        params[:groupby] = params.delete(:group_by) if params[:group_by]
+        get("#{domain}/campaigns/#{id}/stats", params)
+      end
+
+      # Fetches clicks aggregated by one or more parameters.
+      #
+      # @param id [String] a campaign ID
+      # @option params [String] :group_by optional grouping (link, recipient,
+      #   domain, country, region, city, month, day, hour, minute, daily_hour)
+      # @option params [String] :country optional two-letter country code
+      # @option params [String] :region optional region name or code
+      # @option params [String] :city optional city name
+      # @option params [Fixnum] :limit number of records to return (maximum 100)
+      # @option params [Fixnum] :page results page number
+      # @option params [Boolean] :count if true, return counts instead of
+      #   records
+      # @return [Mash] the response body
+      def clicks(id, params={})
+        params[:groupby] = params.delete(:group_by) if params[:group_by]
+        get("#{domain}/campaigns/#{id}/clicks", params)
+      end
+
+      # Fetches opens aggregated by one or more parameters.
+      #
+      # @param id [String] a campaign ID
+      # @option params [String] :group_by optional grouping (recipient, domain,
+      #   country, region, city, month, day, hour, minute, daily_hour)
+      # @option params [String] :country optional two-letter country code
+      # @option params [String] :region optional region name or code
+      # @option params [String] :city optional city name
+      # @option params [Fixnum] :limit number of records to return (maximum 100)
+      # @option params [Fixnum] :page results page number
+      # @option params [Boolean] :count if true, return counts instead of
+      #   records
+      # @return [Mash] the response body
+      def opens(id, params={})
+        params[:groupby] = params.delete(:group_by) if params[:group_by]
+        get("#{domain}/campaigns/#{id}/opens", params)
+      end
+
+      # Fetches unsubscribes aggregated by one or more parameters.
+      #
+      # @param id [String] a campaign ID
+      # @option params [String] :group_by optional grouping (domain, country,
+      #   region, city, month, day, hour, minute, daily_hour)
+      # @option params [String] :country optional two-letter country code
+      # @option params [String] :region optional region name or code
+      # @option params [String] :city optional city name
+      # @option params [Fixnum] :limit number of records to return (maximum 100)
+      # @option params [Fixnum] :page results page number
+      # @option params [Boolean] :count if true, return counts instead of
+      #   records
+      # @return [Mash] the response body
+      def unsubscribes(id, params={})
+        params[:groupby] = params.delete(:group_by) if params[:group_by]
+        get("#{domain}/campaigns/#{id}/unsubscribes", params)
+      end
+
+      # Fetches complaints aggregated by one or more parameters.
+      #
+      # @param id [String] a campaign ID
+      # @option params [String] :group_by optional grouping (recipient, domain,
+      #   month, day, hour, minute, daily_hour)
+      # @option params [Fixnum] :limit number of records to return (maximum 100)
+      # @option params [Fixnum] :page results page number
+      # @option params [Boolean] :count if true, return counts instead of
+      #   records
+      # @return [Mash] the response body
+      def complaints(id, params={})
+        params[:groupby] = params.delete(:group_by) if params[:group_by]
+        get("#{domain}/campaigns/#{id}/complaints", params)
+      end
+    end
+  end
+end