mailgun-ruby 1.4.4 → 1.4.5

data/README.md

@@ -19,7 +19,7 @@ gem install mailgun-ruby
 Gemfile:
 
 ```ruby
-gem 'mailgun-ruby', '~>1.4.4'
+gem 'mailgun-ruby', '~>1.4.5'
 ```
 
 Usage
@@ -187,6 +187,7 @@ This SDK includes the following components:
 - [Domains](docs/Domains.md)
 - [Webhooks](docs/Webhooks.md)
 - [Account Webhooks](docs/AccountWebhooks.md)
+- [API Keys](docs/ApiKeys.md)
 - [Events](docs/Events.md)
 - [Snippets](docs/Snippets.md)
 - [Subaccounts](docs/Subaccounts.md)

data/docs/ApiKeys.md

@@ -0,0 +1,65 @@
+Mailgun - API Keys
+====================
+
+This is the Mailgun Ruby *API Keys* utilities.
+
+The below assumes you've already installed the Mailgun Ruby SDK in to your
+project. If not, go back to the master README for instructions.
+
+Usage - API Keys
+-----------------------
+
+```ruby
+# First, instantiate the Mailgun Client with your API key
+mg_client = Mailgun::Client.new('your-api-key', 'api.mailgun.net', 'v1')
+api_keys = Mailgun::ApiKeys.new(mg_client)
+```
+
+API Keys methods:
+
+```ruby
+# List API keys
+api_keys.list
+
+# List API keys filtered by kind and domain
+api_keys.list(kind: 'domain', domain_name: 'my.perfect.domain')
+
+# Create a user API key
+api_keys.create(
+  kind: 'user',
+  role: 'admin',
+  description: 'desc'
+)
+
+# Create a sending key for a domain, expiring in 1 day
+api_keys.create(
+  kind: 'domain',
+  domain_name: 'my.perfect.domain',
+  role: 'sending',
+  expiration: 86_400
+)
+
+# Delete an API key
+api_keys.remove('key-id')
+
+# Regenerate the public API key
+api_keys.regenerate
+```
+
+Supported `create` options:
+
+| Option        | Description |
+|---------------|-------------|
+| `kind`        | Type of API key: `domain`, `user` or `web`. Defaults to `user` |
+| `role`        | Key role: `admin`, `basic`, `sending` (for `domain` keys) or `developer` |
+| `domain_name` | Domain to associate with the key, for `domain` keys |
+| `description` | Key description |
+| `expiration`  | Key lifetime in seconds, must be greater than 0 if set |
+| `user_id`     | API key user's ID, should be provided for `web` keys |
+| `user_name`   | API key user's name |
+| `email`       | API key user's email address, should be provided for `web` keys |
+
+More Documentation
+------------------
+See the official [Mailgun API Keys Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/keys)
+for more information

data/docs/Webhooks.md

@@ -18,24 +18,47 @@ hook = Mailgun::Webhooks.new(mg_client)
 hook.list 'my.perfect.domain'
 
 # View a single webhook detail
-hook.info 'my.perfect.domain', 'deliver'
+hook.info 'my.perfect.domain', 'delivered'
 
 # Add a single url for all webhooks
 hook.create_all 'my.perfect.domain', 'https://the.webhook.url/'
 
 # Add a url for a specific webhook
-hook.create 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
+hook.create 'my.perfect.domain', 'delivered', 'https://the.webhook.url/'
 
 # Update the url for a specific webhook
-hook.update 'my.perfect.domain', 'deliver', 'https://the.webhook.url/'
+hook.update 'my.perfect.domain', 'delivered', 'https://the.webhook.url/'
 
 # Remove a url for a specific webhook
-hook.remove 'my.perfect.domain', 'deliver'
+hook.remove 'my.perfect.domain', 'delivered'
 
 # Remove all webhooks for a domain
 hook.remove_all 'my.perfect.domain'
 ```
 
+Usage - Webhooks (v4)
+-----------------------
+
+The v4 endpoints work with a URL across multiple event types in a single request.
+They require a client configured for the `v4` API.
+
+```ruby
+mg_client = Mailgun::Client.new('your-api-key', 'api.mailgun.net', 'v4')
+hook = Mailgun::Webhooks.new(mg_client)
+
+# Associate a url with one or more event types
+hook.create_v4 'my.perfect.domain', url: 'https://the.webhook.url/', event_types: %w[delivered opened]
+
+# Replace the event types associated with a url
+hook.update_v4 'my.perfect.domain', url: 'https://the.webhook.url/', event_types: %w[clicked]
+
+# Remove one or more urls from all event types they are associated with
+hook.remove_v4 'my.perfect.domain', url: 'https://the.webhook.url/'
+hook.remove_v4 'my.perfect.domain', url: ['https://the.webhook.url/', 'https://another.webhook.url/']
+```
+
+Each v4 method returns a Hash of the domain's webhooks keyed by event type.
+
 More Documentation
 ------------------
 See the official [Mailgun Webhooks Docs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-webhooks)

data/lib/mailgun/api_keys/api_keys.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mailgun
+  # A Mailgun::ApiKeys object is a simple CRUD interface to Mailgun Api Keys.
+  # Uses Mailgun
+  class ApiKeys
+    include ApiVersionChecker
+
+    # Public creates a new Mailgun::ApiKeys instance.
+    #   Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v1'))
+      @client = client
+    end
+
+    # Public: List Mailgun API keys
+    #
+    # options - [Hash] of
+    #   domain_name - [String] Domain name filter for domain keys
+    #   kind        - [String] Key kind filter ('domain', 'user', or 'web')
+    #
+    # Retrieve filtered api keys.
+    def list(options = {})
+      res = @client.get('keys', options)
+      res.to_h['items']
+    end
+
+    # Public: Create Mailgun API key
+
+    # options - [Hash] of
+    #   domain_name - [String] Web domain to associate with the key, for keys of 'domain' kind
+    #   kind        - [String] Type of API key ('domain', 'user', or 'web'). Defaults to 'user' if not provided.
+    #   description - [String] Key description
+    #   expiration  - [String] Key lifetime in seconds, must be greater than 0 if set
+    #   role        - [String] Key role ('admin', 'basic' [use in place of analyst],
+    #                          'sending' [use with keys of domain kind], or 'developer')
+    #   user_id     - [String] API Key user's string user ID; should be provided for all keys of 'web' kind
+    #   user_name   - [String] API Key user's name
+    #   email       - [String] API Key user's email address; should be provided for all keys of 'web' kind
+    #
+    # Returns the Api Key object
+    def create(options = {})
+      res = @client.post('keys', options)
+      res.to_h['key']
+    end
+
+    # Public: Delete Mailgun API key
+    #
+    # key_id - [String] The Key ID generated by Mailgun on key creation
+    #
+    # Returns a Boolean of the success
+    def remove(key_id)
+      @client.delete("keys/#{key_id}").status == 200
+    end
+
+    # Public: Regenerate Mailgun Public API key
+    #
+    # Returns new Mailgun Public API key.
+    def regenerate
+      res = @client.post('keys/public', {})
+      res.to_h['key']
+    end
+
+    enforces_api_version 'v1', :list, :create, :remove, :regenerate
+  end
+end

data/lib/mailgun/client.rb

@@ -13,7 +13,7 @@ module Mailgun
                    api_host = Mailgun.api_host || 'api.mailgun.net',
                    api_version = Mailgun.api_version || 'v3',
                    ssl = true,
-                   test_mode = !Mailgun.test_mode.nil?,
+                   test_mode = Mailgun.test_mode ? true : false,
                    timeout = nil,
                    proxy_url = Mailgun.proxy_url)
       endpoint = endpoint_generator(api_host, api_version, ssl)

data/lib/mailgun/version.rb

@@ -2,5 +2,5 @@
 
 # It's the version. Yeay!
 module Mailgun
-  VERSION = '1.4.4'
+  VERSION = '1.4.5'
 end

data/lib/mailgun/webhooks/webhooks.rb

@@ -58,12 +58,13 @@ module Mailgun
     #
     # domain - A String of the domain name (ex. domain.com)
     # action - A String of the action to create a webhook for
-    # url    - A String of the url of the webhook
+    # url    - A String of the url of the webhook, or an Array of up to 3 urls
     #
     # Returns a Boolean of whether the webhook was created
     def create(domain, action, url = '')
       res = @client.post("domains/#{domain}/webhooks", id: action, url: url)
-      res.to_h['webhook']['urls'].include?(url) && res.to_h['message'] == 'Webhook has been created'
+      urls = res.to_h['webhook']['urls']
+      Array(url).all? { |u| urls.include?(u) } && res.to_h['message'] == 'Webhook has been created'
     end
 
     # :nocov:
@@ -84,7 +85,8 @@ module Mailgun
     # Returns true or false
     # :nocov:
     %i[create_all add_all_webhooks].each do |method|
-      define_method(method) do |domain|
+      define_method(method) do |domain, url|
+        url ||= ''
         warn("`#{method}` method will be deprecated in future versions of Mailgun. Please use `create` instead.")
 
         ACTIONS.each do |action|
@@ -97,13 +99,13 @@ module Mailgun
     # Public: Update webhook
     #
     # domain - A String of the domain name (ex. domain.com)
-    # action - A String of the action to create a webhook for
-    # url    - A String of the url of the webhook
+    # action - A String of the action to update the webhook for
+    # url    - A String of the url of the webhook, or an Array of up to 3 urls
     #
     # Returns a Boolean of whether the webhook was updated
     def update(domain, action, url = '')
-      raise Mailgun::ParameterError('Domain not provided to update webhooks') unless domain
-      raise Mailgun::ParameterError('Action not provided to identify webhook to update') unless action
+      raise Mailgun::ParameterError, 'Domain not provided to update webhooks' if domain.to_s.empty?
+      raise Mailgun::ParameterError, 'Action not provided to identify webhook to update' if action.to_s.empty?
 
       res = @client.put("domains/#{domain}/webhooks/#{action}", id: action, url: url)
       res.to_h['message'] == 'Webhook has been updated'
@@ -123,8 +125,8 @@ module Mailgun
     #
     # Returns a Boolean of the success
     def remove(domain, action)
-      raise Mailgun::ParameterError('Domain not provided to remove webhook from') unless domain
-      raise Mailgun::ParameterError('Action not provided to identify webhook to remove') unless action
+      raise Mailgun::ParameterError, 'Domain not provided to remove webhook from' if domain.to_s.empty?
+      raise Mailgun::ParameterError, 'Action not provided to identify webhook to remove' if action.to_s.empty?
 
       @client.delete("domains/#{domain}/webhooks/#{action}").to_h['message'] == 'Webhook has been deleted'
     end
@@ -148,7 +150,7 @@ module Mailgun
       define_method(method) do |domain|
         warn("`#{method}` method will be deprecated in future versions of Mailgun. Please use `remove` instead.")
 
-        raise Mailgun::ParameterError('Domain not provided to remove webhooks from') unless domain
+        raise Mailgun::ParameterError, 'Domain not provided to remove webhooks from' if domain.to_s.empty?
 
         ACTIONS.each do |action|
           remove domain, action
@@ -157,6 +159,43 @@ module Mailgun
     end
     # :nocov:
 
+    # Public: Create webhooks for multiple event types (v4)
+    #
+    # domain      - [String] The domain name to create webhooks for
+    # url         - [String] The webhook URL that will receive POST requests
+    # event_types - [String, Array<String>] Event types to associate with the URL
+    #
+    # Returns a Hash of the domain webhooks keyed by event type
+    def create_v4(domain, url:, event_types:)
+      res = @client.post("domains/#{domain}/webhooks", { url: url, event_types: event_types })
+      res.to_h['webhooks']
+    end
+
+    # Public: Update the event types associated with a webhook URL (v4)
+    #
+    # domain      - [String] The domain name to update webhooks for
+    # url         - [String] The webhook URL to update
+    # event_types - [String, Array<String>] Event types to associate with the URL.
+    #               Replaces the existing associations.
+    #
+    # Returns a Hash of the domain webhooks keyed by event type
+    def update_v4(domain, url:, event_types:)
+      res = @client.put("domains/#{domain}/webhooks", { url: url, event_types: event_types })
+      res.to_h['webhooks']
+    end
+
+    # Public: Delete webhook URLs from all event types they are associated with (v4)
+    #
+    # domain - [String] The domain name to delete webhooks from
+    # url    - [String, Array<String>] The webhook URL(s) to delete
+    #
+    # Returns a Hash of the remaining domain webhooks keyed by event type
+    def remove_v4(domain, url:)
+      res = @client.delete("domains/#{domain}/webhooks", { url: url })
+      res.to_h['webhooks']
+    end
+
     enforces_api_version 'v3', :list, :get, :create, :update, :remove
+    enforces_api_version 'v4', :create_v4, :update_v4, :remove_v4
   end
 end

data/lib/mailgun.rb

@@ -23,6 +23,7 @@ Zeitwerk::Loader.for_gem.tap do |loader|
   loader.ignore("#{__dir__}/railgun.rb")
   loader.ignore("#{__dir__}/railgun")
 
+  loader.collapse("#{__dir__}/mailgun/api_keys")
   loader.collapse("#{__dir__}/mailgun/analytics_tags")
   loader.collapse("#{__dir__}/mailgun/domains")
   loader.collapse("#{__dir__}/mailgun/events")

data/spec/integration/api_keys_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'mailgun'
+
+vcr_opts = { cassette_name: 'api_keys' }
+
+describe 'ApiKeys', order: :defined, vcr: vcr_opts do
+  let(:api_version) { 'v1' }
+  let(:mg_client) { Mailgun::Client.new(APIKEY, APIHOST, api_version, SSL) }
+  let(:mg_obj) { Mailgun::ApiKeys.new(mg_client) }
+
+  it 'creates an api key' do
+    result = mg_obj.create(
+      {
+        kind: 'user',
+        'description': 'test test',
+        'role': 'admin'
+      }
+    )
+
+    expect(result['description']).to eq('test test')
+  end
+
+  it 'gets api keys' do
+    result = mg_obj.list
+
+    expect(result[0]['id']).to eq('test')
+  end
+
+  it 'gets api keys filtered by kind and domain' do
+    result = mg_obj.list(kind: 'domain', domain_name: 'DOMAIN.TEST')
+
+    domain_keys = result.select { |key| key['kind'] == 'domain' }
+    expect(domain_keys.map { |key| key['domain_name'] }).to eq(['DOMAIN.TEST'])
+    expect(result.map { |key| key['kind'] }).not_to include('user', 'web')
+  end
+
+  it 'removes an api key' do
+    result = mg_obj.remove('test')
+
+    expect(result).to be_truthy
+  end
+
+  it 'regenerates public api key' do
+    result = mg_obj.regenerate
+
+    expect(result).to be_truthy
+  end
+end

data/spec/integration/webhook_spec.rb

@@ -43,3 +43,37 @@ describe 'For the webhooks endpoint', order: :defined, vcr: vcr_opts do
     expect(result).to be_truthy
   end
 end
+
+describe 'For the v4 webhooks endpoint', vcr: { cassette_name: 'webhooks_v4' } do
+  let(:mg_client) { Mailgun::Client.new(APIKEY, APIHOST, 'v4', SSL) }
+  let(:mg_obj) { Mailgun::Webhooks.new(mg_client) }
+  let(:domain) { 'DOMAIN.TEST' }
+  let(:url) { 'http://example.com/mailgun/events/v4' }
+
+  describe '#create_v4' do
+    it 'creates webhooks for multiple event types' do
+      result = mg_obj.create_v4(domain, url: url, event_types: %w[accepted delivered])
+
+      expect(result.keys).to contain_exactly('accepted', 'delivered')
+      expect(result['accepted']['urls']).to include(url)
+      expect(result['delivered']['urls']).to include(url)
+    end
+  end
+
+  describe '#update_v4' do
+    it 'replaces the event types associated with a url' do
+      result = mg_obj.update_v4(domain, url: url, event_types: %w[clicked opened])
+
+      expect(result.keys).to contain_exactly('clicked', 'opened')
+      expect(result['clicked']['urls']).to include(url)
+    end
+  end
+
+  describe '#remove_v4' do
+    it 'removes the urls from all event types' do
+      result = mg_obj.remove_v4(domain, url: [url, 'http://example.com/mailgun/events/v4-other'])
+
+      expect(result).to eq({})
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -17,6 +17,8 @@ require 'mailgun'
 
 require 'vcr'
 require 'webmock/rspec'
+# Keep repeated query keys (e.g. ?url=a&url=b) instead of collapsing them to the last value
+WebMock::Config.instance.query_values_notation = :flat_array
 require 'rspec/its'
 
 # WebMock.disable_net_connect!(allow_localhost: true)
@@ -43,6 +45,7 @@ VCR.configure do |c|
   c.hook_into :webmock
   c.default_cassette_options = { record: :new_episodes }
   c.filter_sensitive_data('<APIKEY>') { APIKEY }
+  c.filter_sensitive_data('<BASIC_AUTH>') { ["api:#{APIKEY}"].pack('m0') } if APIKEY
   c.filter_sensitive_data('DOMAIN.TEST') { TESTDOMAIN }
   c.filter_sensitive_data('<PUBKEY>') { PUB_APIKEY }
 

data/spec/unit/client_spec.rb

@@ -54,6 +54,30 @@ describe Mailgun::Client do
     it 'supports EU api host' do
       expect { described_class.new(api_key, 'api.eu.mailgun.net') }.not_to raise_error
     end
+
+    context 'when test_mode is not passed' do
+      around do |example|
+        original = Mailgun.test_mode
+        example.run
+      ensure
+        Mailgun.test_mode = original
+      end
+
+      it 'enables test mode when Mailgun.test_mode is true' do
+        Mailgun.test_mode = true
+        expect(described_class.new(api_key).test_mode?).to be(true)
+      end
+
+      it 'disables test mode when Mailgun.test_mode is false' do
+        Mailgun.test_mode = false
+        expect(described_class.new(api_key).test_mode?).to be(false)
+      end
+
+      it 'disables test mode when Mailgun.test_mode is not set' do
+        Mailgun.test_mode = nil
+        expect(described_class.new(api_key).test_mode?).to be(false)
+      end
+    end
   end
 
   # ---------------------------------------------------------------------------

data/spec/unit/webhooks_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Mailgun::Webhooks do
+  let(:client) { double(:client) }
+  let(:webhooks) { described_class.new(client) }
+  let(:domain) { 'example.com' }
+  let(:url) { 'https://example.com/mailgun/events' }
+
+  %i[create_all add_all_webhooks].each do |method|
+    describe "##{method}" do
+      it 'creates every webhook action with the provided URL' do
+        described_class::ACTIONS.each do |action|
+          expect(webhooks).to receive(:create).with(domain, action, url).ordered
+        end
+
+        expect { webhooks.public_send(method, domain, url) }
+          .to output(/`#{method}` method will be deprecated/).to_stderr
+      end
+    end
+  end
+
+  context 'with v3 endpoints' do
+    let(:client) { instance_double(Mailgun::Client, api_version: 'v3') }
+
+    describe '#create' do
+      let(:urls) { [url, 'https://example.com/other'] }
+      let(:response) do
+        instance_double(Mailgun::Response,
+                        to_h: { 'message' => 'Webhook has been created', 'webhook' => { 'urls' => urls } })
+      end
+
+      before { allow(client).to receive(:post).and_return(response) }
+
+      it 'returns true when a single url was created' do
+        expect(webhooks.create(domain, 'delivered', url)).to be(true)
+      end
+
+      it 'returns true when multiple urls were created' do
+        expect(webhooks.create(domain, 'delivered', urls)).to be(true)
+      end
+
+      it 'returns false when a url is missing from the response' do
+        expect(webhooks.create(domain, 'delivered', [url, 'https://example.com/missing'])).to be(false)
+      end
+    end
+
+    describe 'parameter validation' do
+      it 'raises a ParameterError when the domain is missing' do
+        [nil, ''].each do |blank|
+          expect { webhooks.update(blank, 'delivered', url) }
+            .to raise_error(Mailgun::ParameterError, 'Domain not provided to update webhooks')
+          expect { webhooks.remove(blank, 'delivered') }
+            .to raise_error(Mailgun::ParameterError, 'Domain not provided to remove webhook from')
+        end
+      end
+
+      it 'raises a ParameterError when the action is missing' do
+        [nil, ''].each do |blank|
+          expect { webhooks.update(domain, blank, url) }
+            .to raise_error(Mailgun::ParameterError, 'Action not provided to identify webhook to update')
+          expect { webhooks.remove(domain, blank) }
+            .to raise_error(Mailgun::ParameterError, 'Action not provided to identify webhook to remove')
+        end
+      end
+    end
+  end
+
+  context 'with v4 endpoints' do
+    let(:api_version) { 'v4' }
+    let(:client) { instance_double(Mailgun::Client, api_version: api_version) }
+    let(:response) { instance_double(Mailgun::Response, to_h: { 'webhooks' => { 'accepted' => { 'urls' => [url] } } }) }
+
+    describe '#create_v4' do
+      it 'posts the url and event types to the domain webhooks endpoint' do
+        expect(client).to receive(:post)
+          .with("domains/#{domain}/webhooks", { url: url, event_types: %w[accepted delivered] })
+          .and_return(response)
+
+        expect(webhooks.create_v4(domain, url: url, event_types: %w[accepted delivered]))
+          .to eq('accepted' => { 'urls' => [url] })
+      end
+    end
+
+    describe '#update_v4' do
+      it 'puts the url and event types to the domain webhooks endpoint' do
+        expect(client).to receive(:put)
+          .with("domains/#{domain}/webhooks", { url: url, event_types: 'accepted' })
+          .and_return(response)
+
+        expect(webhooks.update_v4(domain, url: url, event_types: 'accepted'))
+          .to eq('accepted' => { 'urls' => [url] })
+      end
+    end
+
+    describe '#remove_v4' do
+      it 'sends the urls as query params' do
+        urls = [url, 'https://example.com/other']
+        expect(client).to receive(:delete)
+          .with("domains/#{domain}/webhooks", { url: urls })
+          .and_return(response)
+
+        webhooks.remove_v4(domain, url: urls)
+      end
+    end
+
+    context 'when the client api version is not v4' do
+      let(:api_version) { 'v3' }
+
+      it 'raises a ParameterError' do
+        expect { webhooks.create_v4(domain, url: url, event_types: 'accepted') }
+          .to raise_error(Mailgun::ParameterError, /must be v4/)
+        expect { webhooks.update_v4(domain, url: url, event_types: 'accepted') }
+          .to raise_error(Mailgun::ParameterError, /must be v4/)
+        expect { webhooks.remove_v4(domain, url: url) }
+          .to raise_error(Mailgun::ParameterError, /must be v4/)
+      end
+    end
+  end
+end