Add Contacts API functionality

Author: sarco3t

examples/contact.rb renamed to examples/contacts_api.rb

@@ -3,11 +3,11 @@
 require_relative 'mailtrap/action_mailer' if defined? ActionMailer
 require_relative 'mailtrap/mail'
 require_relative 'mailtrap/errors'
-require_relative 'mailtrap/api'
+require_relative 'mailtrap/base_api'
 require_relative 'mailtrap/version'
 require_relative 'mailtrap/email_templates_api'
-require_relative 'mailtrap/contact'
-require_relative 'mailtrap/contact_list'
+require_relative 'mailtrap/contacts_api'
+require_relative 'mailtrap/contact_lists_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  class BaseAPI
+    attr_reader :account_id, :client
+
+    # @param account_id [Integer] The account ID
+    # @param client [Mailtrap::Client] The client instance
+    # @raise [ArgumentError] If account_id is nil
+    def initialize(account_id = ENV.fetch('MAILTRAP_ACCOUNT_ID'), client = Mailtrap::Client.new)
+      raise ArgumentError, 'account_id is required' if account_id.nil?
+
+      @account_id = account_id
+      @client = client
+    end
+
+    private
+
+    def validate_options!(options, supported_options)
+      invalid_options = options.keys - supported_options
+      return if invalid_options.empty?
+
+      raise ArgumentError, "invalid options are given: #{invalid_options}, supported_options: #{supported_options}"
+    end
+
+    def build_entity(options, response_class)
+      response_class.new(options.slice(*response_class.members))
+    end
+  end
+end

lib/mailtrap/api.rb

@@ -1,33 +1,6 @@
 # frozen_string_literal: true
 
 module Mailtrap
-  # Data Transfer Object for Contact Create Request
-  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/284bcc8fd846f-contact-create-request
-  # @attr_reader email [String] The contact's email address (required)
-  # @attr_reader fields [Hash] Object of fields with merge tags
-  # @attr_reader list_ids [Array<Integer>] Array of list IDs
-  ContactCreateRequest = Struct.new(:email, :fields, :list_ids, keyword_init: true) do
-    # @return [Hash] The contact request attributes as a hash
-    def to_h
-      super.compact
-    end
-  end
-
-  # Data Transfer Object for Contact Update Request
-  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/d3efb09dbeda8-contact-update-request
-  # @attr_reader email [String] The contact's email address (required)
-  # @attr_reader fields [Hash] Object of fields with merge tags
-  # @attr_reader list_ids_included [Array<Integer>] Array of list IDs to include
-  # @attr_reader list_ids_excluded [Array<Integer>] Array of list IDs to exclude
-  # @attr_reader unsubscribed [Boolean] Whether to unsubscribe the contact
-  ContactUpdateRequest = Struct.new(:email, :fields, :list_ids_included, :list_ids_excluded, :unsubscribed,
-                                    keyword_init: true) do
-    # @return [Hash] The contact request attributes as a hash
-    def to_h
-      super.compact
-    end
-  end
-
   # Data Transfer Object for Contact
   # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/220a54e31e5ca-contact
   # @attr_reader id [String] The contact ID
@@ -56,7 +29,7 @@ def to_h
   # Data Transfer Object for Contact Update Response
   # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/16eab4fff9740-contact-update-response
   # @attr_reader action [String] The performed action (created/updated)
-  # @attr_reader data [Contact] The contact data
+  # @attr_reader data [Contact, Hash] The contact data
   ContactUpdateResponse = Struct.new(:action, :data, keyword_init: true) do
     def initialize(*)
       super
@@ -68,70 +41,4 @@ def to_h
       super.compact
     end
   end
-
-  class ContactsAPI
-    include Mailtrap::API
-
-    def initialize(account_id, client = Mailtrap::Client.new)
-      @account_id = account_id
-      @client = client
-    end
-
-    # Retrieves a specific contact
-    # @param contact_id [String] The contact identifier, which can be either a UUID or an email address
-    # @return [Contact] Contact object
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def get(contact_id)
-      response = @client.get("#{base_path}/#{contact_id}")
-      build_entity(response[:data], Contact)
-    end
-
-    # Creates a new contact
-    # @param request [ContactCreateRequest, Hash] The contact create request object or a hash with the same attributes
-    # @return [Contact] Created contact object
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def create(request)
-      response = @client.post(base_path, { contact: prepare_request(request, ContactCreateRequest) })
-      build_entity(response[:data], Contact)
-    end
-
-    # Updates an existing contact
-    # @param contact_id [String] The contact ID
-    # @param request [ContactUpdateRequest, Hash] The contact update request object or a hash with the same attributes
-    # @return [ContactUpdateResponse] Response containing the action performed and contact data
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def update(contact_id, request)
-      response = @client.patch(
-        "#{base_path}/#{contact_id}",
-        { contact: prepare_request(request, ContactUpdateRequest) }
-      )
-      build_entity(response, ContactUpdateResponse)
-    end
-
-    # Deletes a contact
-    # @param contact_id [String] The contact ID
-    # @return nil
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def delete(contact_id)
-      @client.delete("#{base_path}/#{contact_id}")
-    end
-
-    private
-
-    def base_path
-      "/api/accounts/#{@account_id}/contacts"
-    end
-  end
 end

lib/mailtrap/base_api.rb

@@ -1,16 +1,6 @@
 # frozen_string_literal: true
 
 module Mailtrap
-  # Data Transfer Object for Contact List Create Request
-  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/e3bba0bfa185e-create-contact-list
-  # @attr_reader name [String] The name of the contact list (required)
-  ContactListRequest = Struct.new(:name, keyword_init: true) do
-    # @return [Hash] The contact list request attributes as a hash
-    def to_h
-      super.compact
-    end
-  end
-
   # Data Transfer Object for Contact List
   # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/6ec7a37234af2-contact-list
   # @attr_reader id [Integer] The contact list ID
@@ -21,76 +11,4 @@ def to_h
       super.compact
     end
   end
-
-  class ContactListsAPI
-    include Mailtrap::API
-
-    def initialize(account_id, client = Mailtrap::Client.new)
-      @account_id = account_id
-      @client = client
-    end
-
-    # Retrieves a specific contact list
-    # @param list_id [Integer] The contact list identifier
-    # @return [ContactList] Contact list object
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def get(list_id)
-      response = @client.get("#{base_path}/#{list_id}")
-      build_entity(response, ContactList)
-    end
-
-    # Creates a new contact list
-    # @param request [ContactListRequest, Hash] The contact list create request object or a hash
-    # @return [ContactList] Created contact list object
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def create(request)
-      response = @client.post(base_path, prepare_request(request, ContactListRequest))
-      build_entity(response, ContactList)
-    end
-
-    # Updates an existing contact list
-    # @param list_id [Integer] The contact list ID
-    # @param request [ContactListRequest, Hash] The contact list update request object or a hash
-    # @return [ContactList] Updated contact list object
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def update(list_id, request)
-      response = @client.patch(
-        "#{base_path}/#{list_id}", prepare_request(request, ContactListRequest)
-      )
-      build_entity(response, ContactList)
-    end
-
-    # Deletes a contact list
-    # @param list_id [Integer] The contact list ID
-    # @return nil
-    # @raise [Mailtrap::Error] If the API request fails with a client or server error
-    # @raise [Mailtrap::AuthorizationError] If the API key is invalid
-    # @raise [Mailtrap::RejectionError] If the server refuses to process the request
-    # @raise [Mailtrap::RateLimitError] If too many requests are made
-    def delete(list_id)
-      @client.delete("#{base_path}/#{list_id}")
-    end
-
-    # Lists all contact lists for the account
-    # @return [Array<ContactList>] Array of contact list objects
-    def list
-      response = @client.get(base_path)
-      response.map { |list| build_entity(list, ContactList) }
-    end
-
-    private
-
-    def base_path
-      "/api/accounts/#{@account_id}/contacts/lists"
-    end
-  end
 end

lib/mailtrap/contact.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'contact_list'
+
+module Mailtrap
+  class ContactListsAPI < BaseAPI
+    SUPPORTED_OPTIONS = %i[name].freeze
+    private_constant :SUPPORTED_OPTIONS
+
+    # Retrieves a specific contact list
+    # @param list_id [Integer] The contact list identifier
+    # @return [ContactList] Contact list object
+    # @!macro api_errors
+    def get(list_id)
+      response = client.get("#{base_path}/#{list_id}")
+      build_entity(response, ContactList)
+    end
+
+    # Creates a new contact list
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The contact list name
+    # @return [ContactList] Created contact list object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      validate_options!(options, SUPPORTED_OPTIONS)
+
+      response = client.post(base_path, options)
+      build_entity(response, ContactList)
+    end
+
+    # Updates an existing contact list
+    # @param list_id [Integer] The contact list ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The contact list name
+    # @return [ContactList] Updated contact list object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(list_id, options)
+      validate_options!(options, SUPPORTED_OPTIONS)
+
+      response = client.patch(
+        "#{base_path}/#{list_id}", options
+      )
+      build_entity(response, ContactList)
+    end
+
+    # Deletes a contact list
+    # @param list_id [Integer] The contact list ID
+    # @return nil
+    # @!macro api_errors
+    def delete(list_id)
+      client.delete("#{base_path}/#{list_id}")
+    end
+
+    # Lists all contact lists for the account
+    # @return [Array<ContactList>] Array of contact list objects
+    # @!macro api_errors
+    def list
+      response = client.get(base_path)
+      response.map { |list| build_entity(list, ContactList) }
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts/lists"
+    end
+  end
+end