mailgun-ruby 1.4.1 → 1.4.3

data/spec/unit/connection/test_client.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 require 'time'
 require 'json'
 
 module Mailgun
   class UnitClient < Mailgun::Client
-
     attr_reader :options, :block, :body, :code, :response
 
     def initialize(endpoint, &block)
@@ -14,9 +15,10 @@ module Mailgun
     end
 
     def [](endpoint, &new_block)
-      case
-      when block_given? then self.class.new(endpoint, &new_block)
-      when block        then self.class.new(endpoint, &block)
+      if block_given?
+        self.class.new(endpoint, &new_block)
+      elsif block
+        self.class.new(endpoint, &block)
       else
         self.class.new(endpoint)
       end
@@ -26,10 +28,8 @@ module Mailgun
       perform_data_validation(working_domain, data)
       case data
       when Hash
-        if data.has_key?(:message)
-          if data[:message].is_a?(String)
-            data[:message] = convert_string_to_file(data[:message])
-          end
+        if data.key?(:message)
+          data[:message] = convert_string_to_file(data[:message]) if data[:message].is_a?(String)
           post("#{working_domain}/messages.mime", data)
         else
           post("#{working_domain}/messages", data)
@@ -37,80 +37,133 @@ module Mailgun
       when MessageBuilder
         post("#{working_domain}/messages", data.message)
       else
-        raise ParameterError.new("Unknown data type for data parameter.", data)
+        raise ParameterError.new('Unknown data type for data parameter.', data)
       end
     end
 
-    def post(path, data)
-      begin
-        Mailgun::Response.new(response_generator(@endpoint))
-      rescue => e
-        p e
-        raise CommunicationError.new(e), e.response if e.respond_to? :response
-        raise CommunicationError.new(e.message)
-      end
+    def post(_path, _data)
+      Mailgun::Response.new(response_generator(@endpoint))
+    rescue StandardError => e
+      p e
+      raise CommunicationError.new(e), e.response if e.respond_to? :response
+
+      raise CommunicationError, e.message
     end
 
-    def get(path, query_string = nil)
-      begin
-        Mailgun::Response.new(response_generator(@endpoint))
-      rescue => e
-        raise CommunicationError.new(e), e.response
-      end
+    def get(_path, _query_string = nil)
+      Mailgun::Response.new(response_generator(@endpoint))
+    rescue StandardError => e
+      raise CommunicationError.new(e), e.response
     end
 
-    def put(path, data)
-      begin
-        Mailgun::Response.new(response_generator(@endpoint))
-      rescue => e
-        raise CommunicationError.new(e), e.response
-      end
+    def put(_path, _data)
+      Mailgun::Response.new(response_generator(@endpoint))
+    rescue StandardError => e
+      raise CommunicationError.new(e), e.response
     end
 
-    def delete(path)
-      begin
-        Mailgun::Response.new(response_generator(@endpoint))
-      rescue => e
-        raise CommunicationError.new(e), e.response
-      end
+    def delete(_path)
+      Mailgun::Response.new(response_generator(@endpoint))
+    rescue StandardError => e
+      raise CommunicationError.new(e), e.response
     end
 
     private
 
     def perform_data_validation(working_domain, data)
-      fail ParameterError.new('Missing working domain', working_domain) unless working_domain
+      raise ParameterError.new('Missing working domain', working_domain) unless working_domain
       return true unless data.is_a?(Hash) && data.present?
+
       message = data.respond_to?(:message) ? data.message : data
 
-      fail ParameterError.new(
-        'Missing `to` recipient, message should contain at least 1 recipient',
-        working_domain
-      ) if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
-      fail ParameterError.new(
+      if message.fetch('to', []).empty? && message.fetch(:to, []).empty?
+        raise ParameterError.new(
+          'Missing `to` recipient, message should contain at least 1 recipient',
+          working_domain
+        )
+      end
+      return unless message.fetch('from', []).empty? && message.fetch(:from, []).empty?
+
+      raise ParameterError.new(
         'Missing a `from` sender, message should contain at least 1 `from` sender',
         working_domain
-      ) if message.fetch('from', []).empty? && message.fetch(:from, []).empty?
+      )
     end
 
     def response_generator(resource_endpoint)
-      if resource_endpoint == "messages"
+      if resource_endpoint == 'messages'
         t = Time.now
-        id = "<#{t.to_i}.#{rand(99999999)}.5817@example.com>"
-        return Response.from_hash({ body: JSON.generate({"message" => "Queued. Thank you.", "id" => id}) })
+        id = "<#{t.to_i}.#{rand(99_999_999)}.5817@example.com>"
+        return Response.from_hash({ body: JSON.generate({ 'message' => 'Queued. Thank you.', 'id' => id }) })
       end
-      if resource_endpoint == "bounces"
-        return Response.from_hash({ body: JSON.generate({"total_count" => 1, "items" => {"created_at" => "Fri, 21 Oct 2011 11:02:55 GMT", "status" => 550, "address" => "baz@example.com", "error" => "Message was not accepted -- invalid mailbox. Local mailbox baz@example.com is unavailable: user not found"}}) })
+      if resource_endpoint == 'bounces'
+        return Response.from_hash(
+          { body: JSON.generate(
+            {
+              'total_count' => 1,
+              'items' =>
+                {
+                  'created_at' => 'Fri, 21 Oct 2011 11:02:55 GMT',
+                  'status' => 550,
+                  'address' => 'baz@example.com',
+                  'error' => "Message was not accepted -- invalid mailbox. \
+Local mailbox baz@example.com is unavailable: user not found"
+                }
+            }
+          ) }
+        )
       end
-      if resource_endpoint == "lists"
-        return Response.from_hash({ body: JSON.generate({"member" => {"vars" => {"age" => 26}, "name" => "Foo Bar", "subscribed" => false, "address" => "bar@example.com"}, "message" => "Mailing list member has been updated"}) })
+      if resource_endpoint == 'lists'
+        return Response.from_hash(
+          { body: JSON.generate(
+            {
+              'member' =>
+                {
+                  'vars' => { 'age' => 26 },
+                  'name' => 'Foo Bar',
+                  'subscribed' => false,
+                  'address' => 'bar@example.com'
+                },
+              'message' => 'Mailing list member has been updated'
+            }
+          ) }
+        )
       end
-      if resource_endpoint == "campaigns"
-        return Response.from_hash({ body: JSON.generate({"message" => "Campaign has been deleted", "id" => "ABC123"}) })
-      end
-      if resource_endpoint == "events"
-        return Response.from_hash({ body: JSON.generate({"items" => [], "paging" => {"next"=> "https://api.mailgun.net/v3/thisisatestdomainformailgun.com/events/W3siYiI6ICIyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDVUMDA6NDU6NTEuNzQwOTgzKzAwOjAwIn0sIHsiYiI6ICIyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDVUMDA6NDU6NTEuNzQwOTgzKzAwOjAwIn0sIFsiZiJdLCBudWxsLCB7ImFjY291bnQuaWQiOiAiNGU4MjMwZjYxNDc2ZDg2NzEzMDBjNDc2IiwgImRvbWFpbi5uYW1lIjogInRoaXNpc2F0ZXN0ZG9tYWluZm9ybWFpbGd1bi5jb20iLCAic2V2ZXJpdHkiOiAiTk9UIGludGVybmFsIn0sIDEwMCwgbnVsbF0=", "previous"=> "https://api.mailgun.net/v2/thisisatestdomainformailgun.com/events/W3siYiI6ICIyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDVUMDA6NDU6NTEuNzQwOTgzKzAwOjAwIn0sIHsiYiI6ICIyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDdUMDA6NDU6NTEuNzQxODkyKzAwOjAwIn0sIFsicCIsICJmIl0sIG51bGwsIHsiYWNjb3VudC5pZCI6ICI0ZTgyMzBmNjE0NzZkODY3MTMwMGM0NzYiLCAiZG9tYWluLm5hbWUiOiAidGhpc2lzYXRlc3Rkb21haW5mb3JtYWlsZ3VuLmNvbSIsICJzZXZlcml0eSI6ICJOT1QgaW50ZXJuYWwifSwgMTAwLCBudWxsXQ=="}}) })
+      if resource_endpoint == 'campaigns'
+        return Response.from_hash(
+          {
+            body: JSON.generate(
+              {
+                'message' => 'Campaign has been deleted',
+                'id' => 'ABC123'
+              }
+            )
+          }
+        )
       end
+      return unless resource_endpoint == 'events'
+
+      Response.from_hash(
+        { body: JSON.generate(
+          { 'items' => [],
+            'paging' => {
+              'next' =>
+                "https://api.mailgun.net/v3/thisisatestdomainformailgun.com/events/W3siYiI6I\
+CIyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDVUMDA6NDU6NTEuNzQwOTgzK\
+zAwOjAwIn0sIHsiYiI6ICIyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDVUM\
+DA6NDU6NTEuNzQwOTgzKzAwOjAwIn0sIFsiZiJdLCBudWxsLCB7ImFjY291bnQuaWQiOiAiNGU4MjMwZjYxNDc2ZDg2N\
+zEzMDBjNDc2IiwgImRvbWFpbi5uYW1lIjogInRoaXNpc2F0ZXN0ZG9tYWluZm9ybWFpbGd1bi5jb20iLCAic2V2ZXJpd\
+HkiOiAiTk9UIGludGVybmFsIn0sIDEwMCwgbnVsbF0=",
+              'previous' =>
+                "https://api.mailgun.net/v2/thisisatestdomainformailgun.com/events/W3siYiI6IC\
+IyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDVUMDA6NDU6NTEuNzQwOTgzKzA\
+wOjAwIn0sIHsiYiI6ICIyMDE0LTA1LTA3VDAwOjQ1OjUxLjc0MDg5MiswMDowMCIsICJlIjogIjIwMTQtMDUtMDdUMDA6\
+NDU6NTEuNzQxODkyKzAwOjAwIn0sIFsicCIsICJmIl0sIG51bGwsIHsiYWNjb3VudC5pZCI6ICI0ZTgyMzBmNjE0NzZkO\
+DY3MTMwMGM0NzYiLCAiZG9tYWluLm5hbWUiOiAidGhpc2lzYXRlc3Rkb21haW5mb3JtYWlsZ3VuLmNvbSIsICJzZXZlcm\
+l0eSI6ICJOT1QgaW50ZXJuYWwifSwgMTAwLCBudWxsXQ=="
+            } }
+        ) }
+      )
     end
   end
-
 end

data/spec/unit/events/events_spec.rb

@@ -1,66 +1,85 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe 'The method get' do
-  it 'should return a proper hash of log data.' do
+  it 'returns a proper hash of log data.' do
     @mg_obj = Mailgun::UnitClient.new('events')
-    events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
-    result = events.get()
+    events = Mailgun::Events.new(@mg_obj, 'samples.mailgun.org')
+    result = events.get
 
-    expect(result.body).to include("items")
-    expect(result.body).to include("paging")
+    expect(result.body).to include('items')
+    expect(result.body).to include('paging')
   end
 end
 
 describe 'Pagination' do
-  it 'should return a proper hash of log data.' do
+  it 'returns a proper hash of log data.' do
     @mg_obj = Mailgun::UnitClient.new('events')
-    events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
-    result = events.get()
+    events = Mailgun::Events.new(@mg_obj, 'samples.mailgun.org')
+    result = events.get
 
     json = JSON.parse(result.body)
-    expect(json).to include("paging")
-    expect(json["paging"]).to include("next")
-    expect(json["paging"]).to include("previous")
+    expect(json).to include('paging')
+    expect(json['paging']).to include('next')
+    expect(json['paging']).to include('previous')
   end
 
-  it 'should calculate proper next-page url' do
-    events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
-    output = events.send(:extract_endpoint_from, '/v3/samples.mailgun.org/events/W3siYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIFsiZiJdLCBudWxsLCBbWyJhY2NvdW50LmlkIiwgIjU4MDUyMTg2NzhmYTE2MTNjNzkwYjUwZiJdLCBbImRvbWFpbi5uYW1lIiwgInNhbmRib3gyOTcwMTUyYWYzZDM0NTU5YmZjN2U3MTcwM2E2Y2YyNC5tYWlsZ3VuLm9yZyJdXSwgMTAwLCBudWxsXQ==')
+  it 'calculates proper next-page url' do
+    events = Mailgun::Events.new(@mg_obj, 'samples.mailgun.org')
+    output = events.send(
+      :extract_endpoint_from,
+      "/v3/samples.mailgun.org/events/W3siYiI6ICIyMDE3LTA1\
+LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMj\
+A6MDY6NTQuNTc3KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTEwVDIwOjA2\
+OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNT\
+c3KzAwOjAwIn0sIFsiZiJdLCBudWxsLCBbWyJhY2NvdW50LmlkIiwgIjU4\
+MDUyMTg2NzhmYTE2MTNjNzkwYjUwZiJdLCBbImRvbWFpbi5uYW1lIiwgIn\
+NhbmRib3gyOTcwMTUyYWYzZDM0NTU5YmZjN2U3MTcwM2E2Y2YyNC5tYWls\
+Z3VuLm9yZyJdXSwgMTAwLCBudWxsXQ=="
+    )
 
-    expect(output).to eq 'W3siYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIFsiZiJdLCBudWxsLCBbWyJhY2NvdW50LmlkIiwgIjU4MDUyMTg2NzhmYTE2MTNjNzkwYjUwZiJdLCBbImRvbWFpbi5uYW1lIiwgInNhbmRib3gyOTcwMTUyYWYzZDM0NTU5YmZjN2U3MTcwM2E2Y2YyNC5tYWlsZ3VuLm9yZyJdXSwgMTAwLCBudWxsXQ=='
+    expect(output).to eq "W3siYiI6ICIyMDE3LTA1LTEwVDIwOjA2O\
+jU0LjU3NiswMDowMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3\
+KzAwOjAwIn0sIHsiYiI6ICIyMDE3LTA1LTEwVDIwOjA2OjU0LjU3NiswMDo\
+wMCIsICJlIjogIjIwMTctMDUtMDhUMjA6MDY6NTQuNTc3KzAwOjAwIn0sIF\
+siZiJdLCBudWxsLCBbWyJhY2NvdW50LmlkIiwgIjU4MDUyMTg2NzhmYTE2M\
+TNjNzkwYjUwZiJdLCBbImRvbWFpbi5uYW1lIiwgInNhbmRib3gyOTcwMTUy\
+YWYzZDM0NTU5YmZjN2U3MTcwM2E2Y2YyNC5tYWlsZ3VuLm9yZyJdXSwgMTA\
+wLCBudWxsXQ=="
   end
 end
 
 describe 'The method next' do
-  it 'should return the next series of data.' do
+  it 'returns the next series of data.' do
     @mg_obj = Mailgun::UnitClient.new('events')
-    events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
-    result = events.next()
+    events = Mailgun::Events.new(@mg_obj, 'samples.mailgun.org')
+    result = events.next
 
-    expect(result.body).to include("items")
-    expect(result.body).to include("paging")
+    expect(result.body).to include('items')
+    expect(result.body).to include('paging')
   end
 end
 
 describe 'The method previous' do
-  it 'should return the previous series of data.' do
+  it 'returns the previous series of data.' do
     @mg_obj = Mailgun::UnitClient.new('events')
-    events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
-    result = events.previous()
+    events = Mailgun::Events.new(@mg_obj, 'samples.mailgun.org')
+    result = events.previous
 
-    expect(result.body).to include("items")
-    expect(result.body).to include("paging")
+    expect(result.body).to include('items')
+    expect(result.body).to include('paging')
   end
 end
 
 describe 'The method each' do
-  it 'should iterate over all event items.' do
+  it 'iterates over all event items.' do
     @mg_obj = Mailgun::UnitClient.new('events')
-    events = Mailgun::Events.new(@mg_obj, "samples.mailgun.org")
+    events = Mailgun::Events.new(@mg_obj, 'samples.mailgun.org')
     # Events from the UnitClient are actually empty.
     count = 0
-    events.each do |e|
-      count = count + 1
+    events.each do |_e|
+      count += 1
     end
 
     # Better than nothing..

data/spec/unit/exceptions/exceptions_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 RSpec.describe Mailgun::CommunicationError do
@@ -9,22 +11,21 @@ RSpec.describe Mailgun::CommunicationError do
         end.not_to raise_error
       end
 
-      context "when the Response body has an `Error` property" do
-        it "uses the `Error` property as the API message" do
+      context 'when the Response body has an `Error` property' do
+        it 'uses the `Error` property as the API message' do
           subject = described_class.new('Boom!', { status: 401, body: '{"Error":"unauthorized"}' })
 
-          expect(subject.message).to eq("Boom!: unauthorized")
+          expect(subject.message).to eq('Boom!: unauthorized')
         end
       end
 
-      context "when the Response body has an `error` property" do
-        it "uses the `Error` property as the API message" do
+      context 'when the Response body has an `error` property' do
+        it 'uses the `Error` property as the API message' do
           subject = described_class.new('Boom!', { status: 401, body: '{"error":"not found"}' })
 
-          expect(subject.message).to eq("Boom!: not found")
+          expect(subject.message).to eq('Boom!: not found')
         end
       end
-
     end
   end
 end

data/spec/unit/helpers/api_version_checker_spec.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+require 'mailgun'
+require 'mailgun/helpers/api_version_checker'
+
+describe Mailgun::ApiVersionChecker do
+  # Build a minimal host class that includes the module, with a controllable
+  # @client so we can set api_version per example.
+  subject(:instance) { host_class.new(client) }
+
+  let(:client) { double(:client) }
+
+  let(:host_class) do
+    Class.new do
+      include Mailgun::ApiVersionChecker
+
+      attr_reader :result
+
+      def initialize(client)
+        @client = client
+      end
+
+      def do_something(arg = nil)
+        @result = arg || :called
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────────────────
+  # .included / module structure
+  # ──────────────────────────────────────────────────────────────────────────
+
+  describe '.included' do
+    it 'extends the including class with ClassMethods' do
+      expect(host_class).to respond_to(:requires_api_version)
+      expect(host_class).to respond_to(:enforces_api_version)
+    end
+
+    it 'does not expose ClassMethods as instance methods' do
+      expect(instance).not_to respond_to(:requires_api_version)
+      expect(instance).not_to respond_to(:enforces_api_version)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────────────────
+  # .requires_api_version  (warns but still calls through)
+  # ──────────────────────────────────────────────────────────────────────────
+
+  describe '.requires_api_version' do
+    before { host_class.requires_api_version('v3', :do_something) }
+
+    context 'when the client is on the expected version' do
+      before { allow(client).to receive(:api_version).and_return('v3') }
+
+      it 'does not emit a warning' do
+        expect { instance.do_something }.not_to output.to_stderr
+      end
+
+      it 'still calls the original method' do
+        instance.do_something(:payload)
+        expect(instance.result).to eq(:payload)
+      end
+
+      it 'forwards all arguments to the original method' do
+        instance.do_something(:forwarded_arg)
+        expect(instance.result).to eq(:forwarded_arg)
+      end
+    end
+
+    context 'when the client is on a different version' do
+      before { allow(client).to receive(:api_version).and_return('v4') }
+
+      it 'emits a warning to stderr' do
+        expect { instance.do_something }
+          .to output(/WARN: Client api version must be v3/).to_stderr
+      end
+
+      it 'still calls the original method despite the warning' do
+        instance.do_something(:payload)
+        expect(instance.result).to eq(:payload)
+      end
+
+      it 'warning message includes the expected version' do
+        expect { instance.do_something }
+          .to output(/v3/).to_stderr
+      end
+    end
+
+    it 'wraps multiple methods when given a list' do
+      host_class.class_eval { def do_other = @result = :other }
+      host_class.requires_api_version('v3', :do_something, :do_other)
+
+      allow(client).to receive(:api_version).and_return('v4')
+
+      expect { instance.do_something }.to output(/v3/).to_stderr
+      expect { instance.do_other }.to output(/v3/).to_stderr
+    end
+
+    it 'wraps only the listed methods, leaving others unwrapped' do
+      host_class.class_eval { def unwrapped = @result = :unwrapped }
+      host_class.requires_api_version('v3', :do_something)
+
+      allow(client).to receive(:api_version).and_return('v4')
+
+      # unwrapped should not warn
+      expect { instance.unwrapped }.not_to output.to_stderr
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────────────────
+  # .enforces_api_version  (raises on version mismatch)
+  # ──────────────────────────────────────────────────────────────────────────
+
+  describe '.enforces_api_version' do
+    before { host_class.enforces_api_version('v3', :do_something) }
+
+    context 'when the client is on the expected version' do
+      before { allow(client).to receive(:api_version).and_return('v3') }
+
+      it 'does not raise' do
+        expect { instance.do_something }.not_to raise_error
+      end
+
+      it 'calls the original method' do
+        instance.do_something(:payload)
+        expect(instance.result).to eq(:payload)
+      end
+
+      it 'forwards all arguments to the original method' do
+        instance.do_something(:forwarded_arg)
+        expect(instance.result).to eq(:forwarded_arg)
+      end
+    end
+
+    context 'when the client is on a different version' do
+      before { allow(client).to receive(:api_version).and_return('v4') }
+
+      it 'raises Mailgun::ParameterError' do
+        expect { instance.do_something }
+          .to raise_error(Mailgun::ParameterError)
+      end
+
+      it 'raises with a message including the expected version' do
+        expect { instance.do_something }
+          .to raise_error(Mailgun::ParameterError, /v3/)
+      end
+
+      it 'does not call the original method' do
+        begin
+          instance.do_something
+        rescue StandardError
+          nil
+        end
+        expect(instance.result).to be_nil
+      end
+    end
+
+    it 'wraps multiple methods when given a list' do
+      host_class.class_eval { def do_other = @result = :other }
+      host_class.enforces_api_version('v3', :do_something, :do_other)
+
+      allow(client).to receive(:api_version).and_return('v4')
+
+      expect { instance.do_something }.to raise_error(Mailgun::ParameterError)
+      expect { instance.do_other }.to raise_error(Mailgun::ParameterError)
+    end
+
+    it 'wraps only the listed methods, leaving others unwrapped' do
+      host_class.class_eval { def unwrapped = @result = :unwrapped }
+      host_class.enforces_api_version('v3', :do_something)
+
+      allow(client).to receive(:api_version).and_return('v4')
+
+      expect { instance.unwrapped }.not_to raise_error
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────────────────
+  # requires vs enforces contrast
+  # ──────────────────────────────────────────────────────────────────────────
+
+  describe 'requires_api_version vs enforces_api_version' do
+    before do
+      host_class.class_eval do
+        def soft_method = @result = :soft
+        def hard_method = @result = :hard
+      end
+      host_class.requires_api_version('v3', :soft_method)
+      host_class.enforces_api_version('v3', :hard_method)
+
+      allow(client).to receive(:api_version).and_return('v4')
+    end
+
+    it 'requires_api_version warns but does not raise' do
+      expect { instance.soft_method }.to output(/v3/).to_stderr
+      expect(instance.result).to eq(:soft)
+    end
+
+    it 'enforces_api_version raises and does not call through' do
+      expect { instance.hard_method }.to raise_error(Mailgun::ParameterError)
+      expect(instance.result).not_to eq(:hard)
+    end
+  end
+end

data/spec/unit/lists/opt_in_handler_spec.rb

@@ -1,22 +1,26 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe 'The method generate_hash' do
-  before(:each) do
-    @mailing_list = "mylist@example.com"
-    @secret_app_id = "mysupersecretpassword"
-    @recipient_address = "bob@example.com"
-    @precalculated_hash = "eyJoIjoiMmY3ZmY1MzFlOGJmMjA0OWNhMTI3ZmU4ZTQyNjZkOTljYzhkMTdk%0AMiIsInAiOiJleUpzSWpvaWJYbHNhWE4wUUdWNFlXMXdiR1V1WTI5dElpd2lj%0AaUk2SW1KdllrQmxlR0Z0Y0d4bExtTnZcbmJTSjlcbiJ9%0A"
+  before do
+    @mailing_list = 'mylist@example.com'
+    @secret_app_id = 'mysupersecretpassword'
+    @recipient_address = 'bob@example.com'
+    @precalculated_hash =
+      "eyJoIjoiMmY3ZmY1MzFlOGJmMjA0OWNhMTI3ZmU4ZTQyNjZkOTljYzhkMTdk%0AMiIsInAiOiJleUpzSWpv\
+aWJYbHNhWE4wUUdWNFlXMXdiR1V1WTI5dElpd2lj%0AaUk2SW1KdllrQmxlR0Z0Y0d4bExtTnZcbmJTSjlcbiJ9%0A"
   end
 
   it 'generates a web safe hash for the recipient wishing to subscribe' do
     my_hash = Mailgun::OptInHandler.generate_hash(@mailing_list, @secret_app_id, @recipient_address)
-    
+
     expect(my_hash).to eq(@precalculated_hash)
   end
 
   it 'generates a web safe hash for the recipient wishing to subscribe' do
     validate_result = Mailgun::OptInHandler.validate_hash(@secret_app_id, @precalculated_hash)
-    
+
     expect(validate_result.length).to eq(2)
     expect(validate_result['recipient_address']).to eq(@recipient_address)
     expect(validate_result['mailing_list']).to eq(@mailing_list)