mailgun-ruby 1.4.3 → 1.4.5

data/lib/mailgun/webhooks/account_webhooks.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Mailgun
+  # A Mailgun::AccountWebhooks object is a simple CRUD interface to Account Mailgun Webhooks.
+  # Uses Mailgun
+  class AccountWebhooks
+    include ApiVersionChecker
+
+    # Public creates a new Mailgun::Webhooks 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 account-level webhooks
+    #
+    # webhook_ids - [String] Comma-separated list of webhook IDs to filter results. If specified,
+    #               only webhooks with matching IDs will be returned.
+    #
+    # Retrieve all account-level webhooks or filter by specific webhook IDs.
+    # Returns webhook details including associated event types.
+    def list(webhook_ids = '')
+      res = @client.get('webhooks', webhook_ids: webhook_ids)
+      res.to_h['webhooks']
+    end
+
+    # Public: Create an account-level webhook
+    #
+    # description - [String] Description for the webhook
+    # event_types - [String] Event types to subscribe to. Use multiple times to specify multiple event types.
+    #               Maximum of 3 unique URLs per event type.
+    # url         - [String] URL for webhook to be sent to
+    #
+    # Returns the Unique identifier for the webhook
+    def create(description:, event_types:, url:)
+      res = @client.post('webhooks', { description: description, event_types: event_types, url: url })
+      res.to_h
+    end
+
+    # Public: Delete account-level webhooks
+    #
+    # webhook_ids - [String] Comma-separated list of webhook IDs to delete.
+    #               If provided, only these specific webhooks will be deleted.
+    # all         - [Boolean] The required String of the webhook action to delete
+    #
+    # Returns a Boolean of the success
+    def remove(webhook_ids = nil, all: false)
+      @client.delete('webhooks', { webhook_ids: webhook_ids, all: all }.compact).status == 204
+    end
+
+    # Public: Get account-level webhook by ID
+    #
+    # webhook_id - [String] The webhook ID to retrieve
+    #
+    # Returns webhook details including associated event types.
+    def get(webhook_id)
+      res = @client.get("webhooks/#{webhook_id}")
+      res.to_h
+    end
+
+    # Public: Update an account-level webhook
+    #
+    # description - [String] Description for the webhook
+    # event_types - [String] Event types to subscribe to. Use multiple times to specify multiple event types.
+    #               Maximum of 3 unique URLs per event type.
+    # url         - [String] URL for webhook to be sent to
+    #
+    # Returns a Boolean of the success
+    def update(webhook_id, description:, event_types:, url:)
+      @client.put("webhooks/#{webhook_id}",
+                  { description: description, event_types: event_types, url: url }).status == 204
+    end
+
+    # Public: Delete account-level webhook by ID
+    #
+    # webhook_id - [String] The webhook ID to delete
+    #
+    # Returns a Boolean of the success
+    def remove_by_id(webhook_id)
+      @client.delete("webhooks/#{webhook_id}").status == 204
+    end
+
+    enforces_api_version 'v1', :list, :create, :remove, :get, :update, :remove_by_id
+  end
+end

data/lib/mailgun/webhooks/webhooks.rb

@@ -4,6 +4,8 @@ module Mailgun
   # A Mailgun::Webhooks object is a simple CRUD interface to Mailgun Webhooks.
   # Uses Mailgun
   class Webhooks
+    include ApiVersionChecker
+
     ACTIONS = %w[accepted clicked complained delivered opened permanent_fail temporary_fail unsubscribed].freeze
 
     # Public creates a new Mailgun::Webhooks instance.
@@ -22,7 +24,14 @@ module Mailgun
       res = @client.get("domains/#{domain}/webhooks", options)
       res.to_h['webhooks']
     end
-    alias get_webhooks list
+
+    # :nocov:
+
+    def get_webhooks(domain, options = {})
+      warn('`get_webhooks` method will be deprecated in future versions of Mailgun. Please use `list` instead.')
+      list(domain, options)
+    end
+    # :nocov:
 
     # Public: Get webook information for a specific action
     #
@@ -31,27 +40,42 @@ module Mailgun
     #
     # Returns a String of the url for the identified webhook or an
     #   empty String if one is not set
-    def info(domain, action)
+    def get(domain, action)
       res = @client.get("domains/#{domain}/webhooks/#{action}")
       res.to_h['webhook']['urls'] || ''
-    rescue NoMethodError
-      ''
     end
-    alias get_webhook_url info
+
+    # :nocov:
+    %i[info get_webhook_url].each do |method|
+      define_method(method) do |domain, action|
+        warn("`#{method}` method will be deprecated in future versions of Mailgun. Please use `get` instead.")
+        get(domain, action)
+      end
+    end
+    # :nocov:
 
     # Public: Add 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
+    # 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
-    alias add create
-    alias add_webhook create
+
+    # :nocov:
+    %i[add add_webhook].each do |method|
+      define_method(method) do |domain, action, url|
+        url ||= ''
+        warn("`#{method}` method will be deprecated in future versions of Mailgun. Please use `create` instead.")
+        create(domain, action, url)
+      end
+    end
+    # :nocov:
 
     # Public: Sets all webhooks to the same URL
     #
@@ -59,31 +83,40 @@ module Mailgun
     # url    - A String of the url to set all webhooks to
     #
     # Returns true or false
-    def create_all(domain, url = '')
-      ACTIONS.each do |action|
-        add_webhook domain, action, url
+    # :nocov:
+    %i[create_all add_all_webhooks].each do |method|
+      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|
+          create domain, action, url
+        end
       end
-      true
-    rescue StandardError
-      false
     end
-    alias add_all_webhooks create_all
+    # :nocov:
 
     # 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['webhook']['urls'] == url && res.to_h['message'] == 'Webhook has been updated'
+      res.to_h['message'] == 'Webhook has been updated'
+    end
+
+    # :nocov:
+    def update_webhook(domain, action, url = '')
+      warn('`update_webhook` method will be deprecated in future versions of Mailgun. Please use `update` instead.')
+      update(domain, action, url)
     end
-    alias update_webhook update
+    # :nocov:
 
     # Public: Delete a specific webhook
     #
@@ -92,29 +125,77 @@ 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'
-    rescue Mailgun::CommunicationError
-      false
     end
-    alias delete remove
-    alias delete_webhook remove
+
+    # :nocov:
+    %i[delete delete_webhook].each do |method|
+      define_method(method) do |domain, action|
+        warn("`#{method}` method will be deprecated in future versions of Mailgun. Please use `remove` instead.")
+        remove(domain, action)
+      end
+    end
+    # :nocov:
 
     # Public: Delete all webhooks for a domain
     #
     # domain - A required String of the domain to remove all webhooks for
     #
     # Returns a Boolean on the success
-    def remove_all(domain)
-      raise Mailgun::ParameterError('Domain not provided to remove webhooks from') unless domain
+    # :nocov:
+    %i[remove_all delete_all delete_all_webooks].each do |method|
+      define_method(method) do |domain|
+        warn("`#{method}` method will be deprecated in future versions of Mailgun. Please use `remove` instead.")
 
-      ACTIONS.each do |action|
-        delete_webhook domain, action
+        raise Mailgun::ParameterError, 'Domain not provided to remove webhooks from' if domain.to_s.empty?
+
+        ACTIONS.each do |action|
+          remove domain, action
+        end
       end
     end
-    alias delete_all remove_all
-    alias delete_all_webooks remove_all
+    # :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/account_webhooks_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'mailgun'
+
+vcr_opts = { cassette_name: 'account_webhooks' }
+
+describe 'For the webhooks endpoint', 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::AccountWebhooks.new(mg_client) }
+
+  it 'creates a webhook' do
+    result = mg_obj.create(
+      description: 'test',
+      event_types: 'accepted',
+      url: 'http://example.com/mailgun/events'
+    )
+
+    expect(result).to have_key('webhook_id')
+  end
+
+  it 'gets a webhook' do
+    result = mg_obj.get('test')
+
+    expect(result['url']).to eq('http://example.com/mailgun/events')
+  end
+
+  it 'gets a list of all account webhooks' do
+    result = mg_obj.list
+
+    expect(result[0]['url']).to eq('http://example.com/mailgun/events')
+  end
+
+  it 'updates a webhook' do
+    result = mg_obj.update(
+      'test',
+      description: 'test2',
+      event_types: 'accepted',
+      url: 'http://example.com/mailgun/events'
+    )
+
+    expect(result).to be_truthy
+  end
+
+  it 'removes a webhook' do
+    result = mg_obj.remove_by_id('test')
+
+    expect(result).to be_truthy
+  end
+
+  it 'removes all webhooks' do
+    result = mg_obj.remove(all: true)
+
+    expect(result).to be_truthy
+  end
+end

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/domain_keys_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'mailgun'
+
+vcr_opts = { cassette_name: 'domains' }
+
+describe 'DomainKeys', vcr: vcr_opts do
+  let(:api_version) { APIVERSION }
+  let(:mg_client) { Mailgun::Client.new(APIKEY, APIHOST, api_version, SSL) }
+  let(:mg_obj) { Mailgun::DomainKeys.new(mg_client) }
+  let(:domain) { 'integration-test.domain.invalid' }
+
+  describe '#list_domain_keys' do
+    let(:api_version) { 'v1' }
+
+    it 'lists all domain keys' do
+      result = mg_obj.list_domain_keys(
+        {
+          signing_domain: domain
+        }
+      )
+
+      expect(result).to include('items')
+      expect(result['items'].first['selector']).to eq('k1')
+    end
+  end
+
+  describe '#create_domain_key' do
+    let(:api_version) { 'v1' }
+
+    it 'creates a domain key' do
+      result = mg_obj.create_domain_key(
+        {
+          signing_domain: domain,
+          selector: 'test'
+        }
+      )
+
+      expect(result['signing_domain']).to eq(domain)
+      expect(result['selector']).to eq('test')
+    end
+  end
+
+  describe '#delete_domain_key' do
+    let(:api_version) { 'v1' }
+
+    it 'deletes a domain key' do
+      result = mg_obj.delete_domain_key(
+        {
+          signing_domain: domain,
+          selector: 'test'
+        }
+      )
+
+      expect(result['message']).to eq('success')
+    end
+  end
+
+  describe '#activate_domain_key' do
+    let(:api_version) { 'v4' }
+
+    it 'activates a domain key' do
+      result = mg_obj.activate_domain_key(
+        domain,
+        'mailo1'
+      )
+
+      expect(result['message']).to eq('domain key activated')
+    end
+  end
+
+  describe '#get_domain_keys' do
+    let(:api_version) { 'v4' }
+
+    it 'lists the domain keys for a specified signing domain' do
+      result = mg_obj.get_domain_keys(
+        domain
+      )
+
+      expect(result).to include('items')
+      expect(result['items'].first['selector']).to eq('mailo1')
+    end
+  end
+
+  describe '#deactivate_domain_key' do
+    let(:api_version) { 'v4' }
+
+    it 'deactivates a domain key' do
+      result = mg_obj.deactivate_domain_key(
+        domain,
+        'tetetet'
+      )
+
+      expect(result['message']).to eq('domain key deactivated')
+    end
+  end
+
+  describe '#update_domain_dkim_authority' do
+    it 'updates the DKIM authority for a domain' do
+      result = mg_obj.update_domain_dkim_authority(
+        domain,
+        {
+          self: true
+        }
+      )
+
+      expect(result['message']).to eq('Domain DKIM authority has not been changed')
+    end
+  end
+
+  describe '#update_domain_dkim_selector' do
+    it 'updates the DKIM selector for a domain' do
+      result = mg_obj.update_domain_dkim_selector(
+        domain,
+        {
+          dkim_selector: 'mailo1'
+        }
+      )
+
+      expect(result['message']).to eq('DKIM selector changed')
+    end
+  end
+end

data/spec/integration/domains_spec.rb

@@ -73,119 +73,6 @@ describe 'For the domains endpoint', vcr: vcr_opts do
     end
   end
 
-  context 'Domain::Keys methods' do
-    describe '#list_domain_keys' do
-      let(:api_version) { 'v1' }
-
-      it 'lists all domain keys' do
-        result = mg_obj.list_domain_keys(
-          {
-            signing_domain: domain
-          }
-        )
-
-        expect(result).to include('items')
-        expect(result['items'].first['selector']).to eq('k1')
-      end
-    end
-
-    describe '#create_domain_key' do
-      let(:api_version) { 'v1' }
-
-      it 'creates a domain key' do
-        result = mg_obj.create_domain_key(
-          {
-            signing_domain: domain,
-            selector: 'test'
-          }
-        )
-
-        expect(result['signing_domain']).to eq(domain)
-        expect(result['selector']).to eq('test')
-      end
-    end
-
-    describe '#delete_domain_key' do
-      let(:api_version) { 'v1' }
-
-      it 'deletes a domain key' do
-        result = mg_obj.delete_domain_key(
-          {
-            signing_domain: domain,
-            selector: 'test'
-          }
-        )
-
-        expect(result['message']).to eq('success')
-      end
-    end
-
-    describe '#activate_domain_key' do
-      let(:api_version) { 'v4' }
-
-      it 'activates a domain key' do
-        result = mg_obj.activate_domain_key(
-          domain,
-          'mailo1'
-        )
-
-        expect(result['message']).to eq('domain key activated')
-      end
-    end
-
-    describe '#get_domain_keys' do
-      let(:api_version) { 'v4' }
-
-      it 'lists the domain keys for a specified signing domain' do
-        result = mg_obj.get_domain_keys(
-          domain
-        )
-
-        expect(result).to include('items')
-        expect(result['items'].first['selector']).to eq('mailo1')
-      end
-    end
-
-    describe '#deactivate_domain_key' do
-      let(:api_version) { 'v4' }
-
-      it 'deactivates a domain key' do
-        result = mg_obj.deactivate_domain_key(
-          domain,
-          'tetetet'
-        )
-
-        expect(result['message']).to eq('domain key deactivated')
-      end
-    end
-
-    describe '#update_domain_dkim_authority' do
-      it 'updates the DKIM authority for a domain' do
-        result = mg_obj.update_domain_dkim_authority(
-          domain,
-          {
-            self: true
-          }
-        )
-
-        expect(result['message']).to eq('Domain DKIM authority has not been changed')
-      end
-    end
-
-    describe '#update_domain_dkim_selector' do
-      it 'updates the DKIM selector for a domain' do
-        result = mg_obj.update_domain_dkim_selector(
-          domain,
-          {
-            dkim_selector: 'mailo1'
-          }
-        )
-
-        expect(result['message']).to eq('DKIM selector changed')
-      end
-    end
-  end
-
   context 'Domain::Tracking methods' do
     # TODO: add missing:
     # get_domain_tracking_certificate