Add Contacts API functionality

Author: sarco3t

examples/contact.rb

@@ -0,0 +1,31 @@
+require 'bundler/setup'
+require 'mailtrap'
+account_id = 1_111_111
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+
+contact_list = Mailtrap::ContactList.new(account_id, client)
+list = contact_list.create(name: 'Test List')
+
+contacts = Mailtrap::Contact.new(account_id, client)
+contact = contacts.create(email: '[email protected]', fields: { first_name: 'John Doe' }, list_ids: [list.id])
+puts "Created Contact: #{contact.id}"
+
+contact = contacts.get(contact.id)
+puts "Contact: #{contact.email}"
+
+contact = contacts.update(contact.id, email: '[email protected]', fields: { first_name: 'Jane Doe' }, list_ids: [2])
+puts "Updated Contact: #{contact.data.email}"
+
+contacts.delete(contact.data.id)
+puts 'Contact deleted'
+
+lists = contact_list.list
+puts "Contact Lists: #{lists}"
+
+contact_list.update(list.id, name: 'Test List Updated')
+
+list = contact_list.get(list.id)
+puts "Contact List: #{list.name}"
+
+contact_list.delete(list.id)
+puts 'Contact List deleted'

lib/mailtrap.rb

@@ -5,5 +5,7 @@
 require_relative 'mailtrap/errors'
 require_relative 'mailtrap/version'
 require_relative 'mailtrap/template'
+require_relative 'mailtrap/contact'
+require_relative 'mailtrap/contact_list'
 
 module Mailtrap; end

lib/mailtrap/client.rb

@@ -150,7 +150,8 @@ def handle_response(response) # rubocop:disable Metrics/AbcSize, Metrics/Cycloma
         body = json_response(response.body)
         raise Mailtrap::AuthorizationError, [body[:errors] || body[:error]].flatten
       when Net::HTTPForbidden
-        raise Mailtrap::RejectionError, json_response(response.body)[:errors]
+        body = json_response(response.body)
+        raise Mailtrap::RejectionError, [body[:errors] || body[:error]].flatten
       when Net::HTTPPayloadTooLarge
         raise Mailtrap::MailSizeError, ['message too large']
       when Net::HTTPTooManyRequests

lib/mailtrap/contact.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for 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
+  # @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
+  # @attr_reader id [String] The contact ID
+  # @attr_reader email [String] The contact's email address
+  # @attr_reader fields [Hash] Object of fields with merge tags
+  # @attr_reader list_ids [Array<Integer>] Array of list IDs
+  # @attr_reader status [String] The contact status (subscribed/unsubscribed)
+  # @attr_reader created_at [Integer] The creation timestamp
+  # @attr_reader updated_at [Integer] The last update timestamp
+  ContactDTO = Struct.new(
+    :id,
+    :email,
+    :fields,
+    :list_ids,
+    :status,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  ) do
+    # @return [Hash] The contact attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+
+  # Data Transfer Object for Contact Update Response
+  # @attr_reader action [String] The performed action (created/updated)
+  # @attr_reader data [ContactDTO] The contact data
+  ContactUpdateResponse = Struct.new(:action, :data, keyword_init: true) do
+    def initialize(*)
+      super
+      self.data = ContactDTO.new(data) if data.is_a?(Hash)
+    end
+
+    # @return [Hash] The response attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+
+  class Contact
+    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 [ContactDTO] Contact object
+    # @raise [Mailtrap::Error] if the contact is not found or if there's an API error
+    # @example Get contact by UUID
+    #   contact = client.get('019706a8-9612-77be-8586-4f26816b467a')
+    # @example Get contact by email
+    #   contact = client.get('[email protected]')
+    def get(contact_id)
+      response = @client.get("#{base_path}/#{contact_id}")
+      ContactDTO.new(response[:data])
+    end
+
+    # Creates a new contact
+    # @param request [ContactCreateRequest, Hash] The contact create request object or a hash with the same attributes
+    # @return [ContactDTO] Created contact object
+    def create(request)
+      normalised = request.is_a?(ContactCreateRequest) ? request : ContactCreateRequest.new(**request)
+      response = @client.post(base_path, { contact: normalised.to_h })
+      ContactDTO.new(response[:data])
+    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
+    def update(contact_id, request)
+      normalised = request.is_a?(ContactUpdateRequest) ? request : ContactUpdateRequest.new(**request)
+      response = @client.patch("#{base_path}/#{contact_id}", { contact: normalised.to_h })
+      ContactUpdateResponse.new(response)
+    end
+
+    # Deletes a contact
+    # @param contact_id [String] The contact ID
+    # @return [Boolean] true if successful
+    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/contact_list.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact List Create Request
+  # @attr_reader name [String] The name of the contact list (required)
+  ContactListCreateRequest = 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
+  # @attr_reader id [Integer] The contact list ID
+  # @attr_reader name [String] The name of the contact list
+  ContactListDTO = Struct.new(:id, :name, keyword_init: true) do
+    # @return [Hash] The contact list attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+
+  class ContactList
+    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 [ContactListDTO] Contact list object
+    # @raise [Mailtrap::Error] if the contact list is not found or if there's an API error
+    def get(list_id)
+      response = @client.get("#{base_path}/#{list_id}")
+      ContactListDTO.new(response)
+    end
+
+    # Creates a new contact list
+    # @param request [ContactListCreateRequest, Hash] The contact list create request object or a hash
+    # @return [ContactListDTO] Created contact list object
+    def create(request)
+      normalised = request.is_a?(ContactListCreateRequest) ? request : ContactListCreateRequest.new(**request)
+      response = @client.post(base_path, normalised.to_h)
+      ContactListDTO.new(response)
+    end
+
+    # Updates an existing contact list
+    # @param list_id [Integer] The contact list ID
+    # @param request [ContactListCreateRequest, Hash] The contact list update request object or a hash
+    # @return [ContactListDTO] Updated contact list object
+    def update(list_id, request)
+      normalised = request.is_a?(ContactListCreateRequest) ? request : ContactListCreateRequest.new(**request)
+      response = @client.patch("#{base_path}/#{list_id}", normalised.to_h)
+      ContactListDTO.new(response)
+    end
+
+    # Deletes a contact list
+    # @param list_id [Integer] The contact list ID
+    # @return [Boolean] true if successful
+    def delete(list_id)
+      @client.delete("#{base_path}/#{list_id}")
+    end
+
+    # Lists all contact lists for the account
+    # @return [Array<ContactListDTO>] Array of contact list objects
+    def list
+      response = @client.get(base_path)
+      response.map { |list| ContactListDTO.new(list) }
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{@account_id}/contacts/lists"
+    end
+  end
+end

spec/mailtrap/contact_list_spec.rb

@@ -0,0 +1,132 @@
+RSpec.describe Mailtrap::ContactList do
+  let(:client) { described_class.new('1111111', Mailtrap::Client.new(api_key: 'correct-api-key')) }
+  let(:base_url) { 'https://mailtrap.io/api/accounts/1111111' }
+
+  around do |example|
+    VCR.turned_off { example.run }
+  end
+
+  describe '#' do
+    let(:expected_response) do
+      [
+        { 'id' => 1, 'name' => 'List 1' },
+        { 'id' => 2, 'name' => 'List 2' }
+      ]
+    end
+
+    it 'returns all contact lists' do
+      stub_request(:get, "#{base_url}/contacts/lists")
+        .to_return(
+          status: 200,
+          body: expected_response.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      response = client.list
+      expect(response).to be_a(Array)
+      expect(response.length).to eq(2)
+      expect(response.first).to have_attributes(id: 1, name: 'List 1')
+    end
+  end
+
+  describe '#get' do
+    let(:contact_list_id) { 1 }
+    let(:expected_response) do
+      { 'id' => 1, 'name' => 'List 1' }
+    end
+
+    it 'returns a specific contact list' do
+      stub_request(:get, "#{base_url}/contacts/lists/#{contact_list_id}")
+        .to_return(
+          status: 200,
+          body: expected_response.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      response = client.get(contact_list_id)
+      expect(response).to have_attributes(id: 1, name: 'List 1')
+    end
+
+    it 'raises error when contact list not found' do
+      stub_request(:get, "#{base_url}/contacts/lists/999")
+        .to_return(
+          status: 404,
+          body: { 'error' => 'Not Found' }.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      expect { client.get(999) }.to raise_error(Mailtrap::Error)
+    end
+  end
+
+  describe '#create' do
+    let(:contact_list_name) { 'List 1' }
+    let(:expected_response) do
+      { 'id' => 1, 'name' => contact_list_name }
+    end
+
+    it 'creates a new contact list' do
+      stub_request(:post, "#{base_url}/contacts/lists")
+        .with(
+          body: { name: contact_list_name }.to_json
+        )
+        .to_return(
+          status: 200,
+          body: expected_response.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      response = client.create(name: contact_list_name)
+      expect(response).to have_attributes(id: 1, name: contact_list_name)
+    end
+
+    it 'raises error when rate limit exceeded' do
+      stub_request(:post, "#{base_url}/contacts/lists")
+        .with(
+          body: { name: contact_list_name }.to_json
+        )
+        .to_return(
+          status: 429,
+          body: { 'errors' => 'Rate limit exceeded' }.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      expect { client.create(name: contact_list_name) }.to raise_error(Mailtrap::Error)
+    end
+  end
+
+  describe '#update' do
+    let(:contact_list_id) { 2 }
+    let(:new_name) { 'List 2' }
+    let(:expected_response) do
+      { 'id' => 2, 'name' => new_name }
+    end
+
+    it 'updates a contact list' do
+      stub_request(:patch, "#{base_url}/contacts/lists/#{contact_list_id}")
+        .with(
+          body: { name: new_name }.to_json
+        )
+        .to_return(
+          status: 200,
+          body: expected_response.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      response = client.update(contact_list_id, name: new_name)
+      expect(response).to have_attributes(id: 2, name: new_name)
+    end
+  end
+
+  describe '#delete' do
+    let(:contact_list_id) { 1 }
+
+    it 'deletes a contact list' do
+      stub_request(:delete, "#{base_url}/contacts/lists/#{contact_list_id}")
+        .to_return(status: 204)
+
+      response = client.delete(contact_list_id)
+      expect(response).to be true
+    end
+  end
+end