mailgun-ruby 1.4.5 → 1.4.6

data/lib/mailgun/routes/routes.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Mailgun
+  # A Mailgun::Routes object is a simple CRUD interface to Mailgun Routes, the rules
+  # that handle incoming email.
+  # Uses Mailgun
+  class Routes
+    include ApiVersionChecker
+
+    enforces_api_version 'v3', :list, :create, :get, :update, :remove, :match
+
+    # Public: creates a new Mailgun::Routes instance.
+    # Defaults to Mailgun::Client
+    def initialize(client = Mailgun::Client.new)
+      @client = client
+    end
+
+    # Public: Get routes
+    #
+    # options - [Hash] of
+    #   limit - [Integer] Maximum number of records to return. (100 by default)
+    #   skip  - [Integer] Number of records to skip. (0 by default)
+    #
+    # Returns [Array] A list of routes (hash)
+    def list(options = {})
+      @client.get('routes', options).to_h['items']
+    end
+
+    # Public: Create a route
+    #
+    # options - [Hash] of
+    #   expression  - [String] The filtering rule, e.g. match_recipient(".*@example.com")
+    #   action      - [String, Array] Action(s) to take when the expression matches,
+    #                 e.g. forward("https://example.com/messages") or stop()
+    #   priority    - [Integer] Smaller numbers are handled first. Defaults to 0
+    #   description - [String] Route description
+    #
+    # Returns [Hash] of the created route
+    def create(options = {})
+      @client.post('routes', options).to_h
+    end
+
+    # Public: Get a route
+    #
+    # route_id - [String] ID of the route
+    #
+    # Returns [Hash] Information on the requested route
+    def get(route_id)
+      require_route_id!(route_id, 'No route ID given to find')
+
+      @client.get("routes/#{route_id}").to_h!
+    end
+
+    # Public: Update a route
+    #
+    # route_id - [String] ID of the route
+    # options - [Hash] of
+    #   expression  - [String] The filtering rule
+    #   action      - [String, Array] Action(s) to take when the expression matches
+    #   priority    - [Integer] Smaller numbers are handled first
+    #   description - [String] Route description
+    #
+    # Returns [Hash] of the updated route
+    def update(route_id, options = {})
+      require_route_id!(route_id, 'No route ID given to update')
+
+      @client.put("routes/#{route_id}", options).to_h
+    end
+
+    # Public: Delete a route
+    #
+    # route_id - [String] ID of the route
+    #
+    # Returns [Boolean] if successful or not
+    def remove(route_id)
+      require_route_id!(route_id, 'No route ID given to remove')
+
+      @client.delete("routes/#{route_id}").status == 200
+    end
+
+    # Public: Find the route that handles an address
+    #
+    # address - [String] Email address to match against the routes
+    #
+    # Returns [Hash] with the matching route
+    def match(address)
+      raise(ParameterError, 'No address given to match', caller) if address.nil? || address.to_s.empty?
+
+      @client.get('routes/match', { address: address }).to_h
+    end
+
+    private
+
+    def require_route_id!(route_id, message)
+      raise(ParameterError, message, caller) if route_id.nil? || route_id.to_s.empty?
+    end
+  end
+end

data/lib/mailgun/tags/analytics_tags.rb

@@ -6,6 +6,8 @@ module Mailgun
   class AnalyticsTags
     include ApiVersionChecker
 
+    enforces_api_version 'v1', :update, :list, :remove, :limits
+
     # Public: creates a new Mailgun::AnalyticsTags instance.
     # Defaults to Mailgun::Client
     def initialize(client = Mailgun::Client.new(Mailgun.api_key, Mailgun.api_host || 'api.mailgun.net', 'v1'))
@@ -61,7 +63,5 @@ module Mailgun
     def limits
       @client.get('analytics/tags/limits').to_h
     end
-
-    enforces_api_version 'v1', :update, :list, :remove, :limits
   end
 end

data/lib/mailgun/tags/tags.rb

@@ -21,7 +21,7 @@ module Mailgun
     #
     # Returns [Array] A list of tags (hash)
     def get_tags(domain, options = {})
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::AnalyticsTags#list')
       raise(ParameterError, 'No domain given to store template on', caller) unless domain
 
       @client.get("#{domain}/tags", options).to_h['items']
@@ -34,7 +34,7 @@ module Mailgun
     #
     # Returns [Hash] Information on the requested tag.
     def get_tag(domain, tag)
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::AnalyticsTags#list')
       raise(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       raise(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
 
@@ -50,7 +50,7 @@ module Mailgun
     #
     # Returns [Boolean] if successful or not
     def update(domain, tag, options = {})
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::AnalyticsTags#update')
       raise(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       raise(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
 
@@ -72,7 +72,7 @@ module Mailgun
     #
     # Returns [Hash] of tag stats info
     def get_tag_stats(domain, tag, options = {})
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::Metrics#account_metrics')
       raise(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       raise(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
 
@@ -87,7 +87,7 @@ module Mailgun
     #
     # Returns [Boolean] if successful or not
     def remove(domain, tag)
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::AnalyticsTags#remove')
       raise(ParameterError, 'No domain given to remove on Mailgun', caller) unless domain
       raise(ParameterError, 'No template name given to find on provided domain', caller) unless tag
 
@@ -101,7 +101,7 @@ module Mailgun
     #
     # Returns [Hash] of countries of origin for a given domain
     def get_countries_aggregated_stats(domain, tag)
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::Metrics#account_metrics')
       raise(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       raise(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
 
@@ -115,7 +115,7 @@ module Mailgun
     #
     # Returns [Hash] of email providers for a given domain
     def get_providers_aggregated_stats(domain, tag)
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::Metrics#account_metrics')
       raise(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       raise(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
 
@@ -129,11 +129,19 @@ module Mailgun
     #
     # Returns [Hash] of devices for a given domain
     def get_devices_aggregated_stats(domain, tag)
-      warn('This API is deprecated in favor of our new analytics Tags API')
+      warn_deprecated(__method__, 'Mailgun::Metrics#account_metrics')
       raise(ParameterError, 'No domain given to find on Mailgun', caller) unless domain
       raise(ParameterError, 'No tag name given to find on provided domain', caller) unless tag
 
       @client.get("#{domain}/tags/#{tag}/stats/aggregates/devices").to_h
     end
+
+    private
+
+    # Internal: Warns that a Tags method is deprecated and names its replacement
+    def warn_deprecated(method_name, replacement)
+      Deprecation.warn("Mailgun::Tags##{method_name}", replacement,
+                       reason: 'Mailgun deprecated the Tags API', removal: 'mailgun-ruby 1.5')
+    end
   end
 end

data/lib/mailgun/version.rb

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

data/lib/mailgun/webhooks/account_webhooks.rb

@@ -6,6 +6,8 @@ module Mailgun
   class AccountWebhooks
     include ApiVersionChecker
 
+    enforces_api_version 'v1', :list, :create, :remove, :get, :update, :remove_by_id
+
     # 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'))
@@ -79,7 +81,5 @@ module Mailgun
     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

@@ -6,6 +6,9 @@ module Mailgun
   class Webhooks
     include ApiVersionChecker
 
+    enforces_api_version 'v3', :list, :get, :create, :update, :remove
+    enforces_api_version 'v4', :create_v4, :update_v4, :remove_v4
+
     ACTIONS = %w[accepted clicked complained delivered opened permanent_fail temporary_fail unsubscribed].freeze
 
     # Public creates a new Mailgun::Webhooks instance.
@@ -28,7 +31,7 @@ module Mailgun
     # :nocov:
 
     def get_webhooks(domain, options = {})
-      warn('`get_webhooks` method will be deprecated in future versions of Mailgun. Please use `list` instead.')
+      warn_deprecated(__method__, :list)
       list(domain, options)
     end
     # :nocov:
@@ -48,7 +51,7 @@ module Mailgun
     # :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.")
+        warn_deprecated(method, :get)
         get(domain, action)
       end
     end
@@ -71,7 +74,7 @@ module Mailgun
     %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.")
+        warn_deprecated(method, :create)
         create(domain, action, url)
       end
     end
@@ -87,7 +90,7 @@ module Mailgun
     %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.")
+        warn_deprecated(method, :create)
 
         ACTIONS.each do |action|
           create domain, action, url
@@ -113,7 +116,7 @@ module Mailgun
 
     # :nocov:
     def update_webhook(domain, action, url = '')
-      warn('`update_webhook` method will be deprecated in future versions of Mailgun. Please use `update` instead.')
+      warn_deprecated(__method__, :update)
       update(domain, action, url)
     end
     # :nocov:
@@ -134,7 +137,7 @@ module Mailgun
     # :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.")
+        warn_deprecated(method, :remove)
         remove(domain, action)
       end
     end
@@ -148,7 +151,7 @@ module Mailgun
     # :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.")
+        warn_deprecated(method, :remove)
 
         raise Mailgun::ParameterError, 'Domain not provided to remove webhooks from' if domain.to_s.empty?
 
@@ -195,7 +198,12 @@ module Mailgun
       res.to_h['webhooks']
     end
 
-    enforces_api_version 'v3', :list, :get, :create, :update, :remove
-    enforces_api_version 'v4', :create_v4, :update_v4, :remove_v4
+    private
+
+    # Internal: Warns that a Webhooks method is deprecated and names its replacement
+    def warn_deprecated(method_name, replacement)
+      Deprecation.warn("Mailgun::Webhooks##{method_name}", "Mailgun::Webhooks##{replacement}",
+                       removal: 'a future version of mailgun-ruby')
+    end
   end
 end

data/lib/mailgun.rb

@@ -33,6 +33,7 @@ Zeitwerk::Loader.for_gem.tap do |loader|
   loader.collapse("#{__dir__}/mailgun/logs")
   loader.collapse("#{__dir__}/mailgun/messages")
   loader.collapse("#{__dir__}/mailgun/metrics")
+  loader.collapse("#{__dir__}/mailgun/routes")
   loader.collapse("#{__dir__}/mailgun/subaccounts")
   loader.collapse("#{__dir__}/mailgun/tags")
   loader.collapse("#{__dir__}/mailgun/templates")