added ContactImportAPI

Author: sarco3t

examples/contacts_api.rb

@@ -4,6 +4,7 @@
 contact_lists = Mailtrap::ContactListsAPI.new 3229, client
 contacts = Mailtrap::ContactsAPI.new 3229, client
 contact_fields = Mailtrap::ContactFieldsAPI.new 3229, client
+contact_imports = Mailtrap::ContactImportsAPI.new 3229, client
 
 # Set your API credentials as environment variables
 # export MAILTRAP_API_KEY='your-api-key'
@@ -12,6 +13,7 @@
 # contact_lists = Mailtrap::ContactListsAPI.new
 # contacts = Mailtrap::ContactsAPI.new
 # contact_fields = Mailtrap::ContactFieldsAPI.new
+# contact_imports = Mailtrap::ContactImportsAPI.new
 
 # Create new contact list
 list = contact_lists.create(name: 'Test List')
@@ -135,8 +137,41 @@
 # Delete contact
 contacts.delete(contact.id)
 
-# Delete contact list
-contact_lists.delete(list.id)
-
 # Delete contact field
 contact_fields.delete(field.id)
+
+# Create a new contact import
+contact_import = contact_imports.create(
+  [
+    {
+      email: 'imported@example.com',
+      fields: {
+        first_name: 'Jane',
+      },
+      list_ids_included: [list.id],
+      list_ids_excluded: []
+    }
+  ]
+)
+# => ContactImport.new(
+#      id: 1,
+#      status: 'created',
+#      list_ids: [1],
+#      created_contacts_count: 1,
+#      updated_contacts_count: 0,
+#      contacts_over_limit_count: 0
+#    )
+
+# Get a contact import by ID
+contact_imports.get(contact_import.id)
+# => ContactImport.new(
+#      id: 1,
+#      status: 'started',
+#      list_ids: [1],
+#      created_contacts_count: 1,
+#      updated_contacts_count: 0,
+#      contacts_over_limit_count: 0
+#    )
+
+# Delete contact list
+contact_lists.delete(list.id)

lib/mailtrap.rb

@@ -8,6 +8,7 @@
 require_relative 'mailtrap/contacts_api'
 require_relative 'mailtrap/contact_lists_api'
 require_relative 'mailtrap/contact_fields_api'
+require_relative 'mailtrap/contact_imports_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap/contact_import.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact Import
+  # @attr_reader id [String] The contact import ID
+  # @attr_reader status [String] The status of the import (created, started, finished, failed)
+  # @attr_reader created_contacts_count [Integer, nil] Number of contacts created in this import
+  # @attr_reader updated_contacts_count [Integer, nil] Number of contacts updated in this import
+  # @attr_reader contacts_over_limit_count [Integer, nil] Number of contacts over the allowed limit
+  ContactImport = Struct.new(
+    :id,
+    :status,
+    :created_contacts_count,
+    :updated_contacts_count,
+    :contacts_over_limit_count,
+    keyword_init: true
+  ) do
+    # @return [Hash] The contact attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

lib/mailtrap/contact_imports_api.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'contact_import'
+
+module Mailtrap
+  class ContactImportsAPI
+    include BaseAPI
+
+    self.supported_options = %i[email fields list_ids_included list_ids_excluded]
+
+    self.response_class = ContactImport
+
+    # Retrieves a specific contact import
+    # @param import_id [String] The contact import identifier
+    # @return [ContactImport] Contact import object
+    # @!macro api_errors
+    def get(import_id)
+      base_get(import_id)
+    end
+
+    # Create contacts import
+    # @param contacts [Array<Hash>] Array of contact objects to import
+    #   Each contact object should have the following keys:
+    #   - email [String] The contact's email address
+    #   - fields [Hash] Object of fields in the format: field_merge_tag => String, Integer, Float, Boolean, or ISO-8601 date string (yyyy-mm-dd) # rubocop:disable Layout/LineLength
+    #   - list_ids_included [Array<Integer>] List IDs to include the contact in
+    #   - list_ids_excluded [Array<Integer>] List IDs to exclude the contact from
+    # @return [ContactImport] Created contact list object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(contacts)
+      contacts.each do |contact|
+        validate_options!(contact, supported_options)
+      end
+      response = client.post(base_path, contacts:)
+      handle_response(response)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts/imports"
+    end
+  end
+end

spec/mailtrap/contact_imports_api_spec.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+RSpec.describe Mailtrap::ContactImportsAPI do
+  let(:client) { described_class.new('1111111', Mailtrap::Client.new(api_key: 'correct-api-key')) }
+  let(:base_url) { 'https://mailtrap.io/api/accounts/1111111' }
+
+  describe '#get' do
+    let(:import_id) { 'import-123' }
+    let(:expected_response) do
+      {
+        'id' => 'import-123',
+        'status' => 'finished',
+        'created_contacts_count' => 10,
+        'updated_contacts_count' => 2,
+        'contacts_over_limit_count' => 0
+      }
+    end
+
+    it 'returns a specific contact import' do
+      stub_request(:get, "#{base_url}/contacts/imports/#{import_id}")
+        .to_return(
+          status: 200,
+          body: expected_response.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      response = client.get(import_id)
+      expect(response).to have_attributes(
+        id: 'import-123',
+        status: 'finished',
+        created_contacts_count: 10,
+        updated_contacts_count: 2,
+        contacts_over_limit_count: 0
+      )
+    end
+
+    it 'raises error when contact import not found' do
+      stub_request(:get, "#{base_url}/contacts/imports/not-found")
+        .to_return(
+          status: 404,
+          body: { 'error' => 'Not Found' }.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      expect { client.get('not-found') }.to raise_error(Mailtrap::Error)
+    end
+  end
+
+  describe '#create' do
+    let(:contacts) do
+      [
+        {
+          email: 'example@example.com',
+          fields: {
+            fname: 'John',
+            age: 30,
+            is_subscribed: true,
+            birthday: '1990-05-15'
+          },
+          list_ids_included: [1, 2],
+          list_ids_excluded: [3]
+        }
+      ]
+    end
+    let(:expected_response) do
+      {
+        'id' => 'import-456',
+        'status' => 'created',
+        'created_contacts_count' => 1,
+        'updated_contacts_count' => 0,
+        'contacts_over_limit_count' => 0
+      }
+    end
+
+    it 'creates a new contact import with hash' do
+      stub_request(:post, "#{base_url}/contacts/imports")
+        .with(body: { contacts: }.to_json)
+        .to_return(
+          status: 200,
+          body: expected_response.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      response = client.create(contacts)
+      expect(response).to have_attributes(
+        id: 'import-456',
+        status: 'created',
+        created_contacts_count: 1,
+        updated_contacts_count: 0,
+        contacts_over_limit_count: 0
+      )
+    end
+
+    it 'raises error when invalid options are provided' do
+      invalid_contacts = [contacts.first.merge(foo: 'bar')]
+      expect { client.create(invalid_contacts) }.to raise_error(ArgumentError, /invalid options are given/)
+    end
+
+    it 'raises error when API returns an error' do
+      stub_request(:post, "#{base_url}/contacts/imports")
+        .with(body: { contacts: }.to_json)
+        .to_return(
+          status: 422,
+          body: { 'errors' => { 'email' => ['is invalid'] } }.to_json,
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+      expect { client.create(contacts) }.to raise_error(Mailtrap::Error)
+    end
+  end
+end