Merge pull request #49 from sarco3t/contacts-api

Contacts API

Author: i7an

examples/contacts_api.rb

@@ -0,0 +1,142 @@
+require 'mailtrap'
+
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+contact_lists = Mailtrap::ContactListsAPI.new 3229, client
+contacts = Mailtrap::ContactsAPI.new 3229, client
+contact_fields = Mailtrap::ContactFieldsAPI.new 3229, client
+
+# Set your API credentials as environment variables
+# export MAILTRAP_API_KEY='your-api-key'
+# export MAILTRAP_ACCOUNT_ID=your-account-id
+
+# contact_lists = Mailtrap::ContactListsAPI.new
+# contacts = Mailtrap::ContactsAPI.new
+# contact_fields = Mailtrap::ContactFieldsAPI.new
+
+# Create new contact list
+list = contact_lists.create(name: 'Test List')
+# => ContactList.new(id: 1, name: 'Test List')
+
+# Get all contact lists
+contact_lists.list
+# => [ContactList.new(id: 1, name: 'Test List')]
+
+# Update contact list
+contact_lists.update(list.id, name: 'Test List Updated')
+# => ContactList.new(id: 1, name: 'Test List Updated')
+
+# Get contact list
+list = contact_lists.get(list.id)
+# => ContactList.new(id: 1, name: 'Test List Updated')
+
+# Create new contact field
+field = contact_fields.create(name: 'Nickname', data_type: 'text', merge_tag: 'nickname')
+# => ContactField.new(id: 1, name: 'Nickname', data_type: 'text', merge_tag: 'nickname')
+
+# Get all contact fields
+contact_fields.list
+# => [ContactField.new(id: 1, name: 'Nickname', data_type: 'text', merge_tag: 'nickname')]
+
+# Update contact field
+contact_fields.update(field.id, name: 'Nickname 2', merge_tag: 'nickname')
+# => ContactField.new(id: 1, name: 'Nickname 2', data_type: 'text', merge_tag: 'nickname')
+
+# Get contact field
+field = contact_fields.get(field.id)
+# => ContactField.new(id: 1, name: 'Nickname 2', data_type: 'text', merge_tag: 'nickname')
+
+# Create new contact with all possible fields
+contact = contacts.create(
+  email: '[email protected]',
+  fields: { field.merge_tag => 'John Doe' },
+  list_ids: [list.id]
+)
+# => Contact.new(
+#      id: 1,
+#      email: '[email protected]',
+#      fields: { 'nickname' => 'John Doe' },
+#      list_ids: [1],
+#      status: 'subscribed',
+#      created_at: 1721212345,
+#      updated_at: 1721212345
+#    )
+contact.newly_created? # => true
+
+# Get contact
+contact = contacts.get(contact.id)
+# => Contact.new(
+#      id: 1,
+#      email: '[email protected]',
+#      fields: { 'nickname' => 'John Doe' },
+#      list_ids: [1],
+#      status: 'subscribed',
+#      created_at: 1721212345,
+#      updated_at: 1721212345
+#    )
+
+# Update contact using id
+updated_contact = contacts.upsert(
+  contact.id,
+  email: '[email protected]',
+  fields: { field.merge_tag => 'Jane Doe' }
+)
+# => Contact.new(
+#      id: 1,
+#      email: '[email protected]',
+#      fields: { 'nickname' => 'Jane Doe' },
+#      list_ids: [1],
+#      status: 'subscribed',
+#      created_at: 1721212345,
+#      updated_at: 1721212350
+#    )
+updated_contact.newly_created? # => false
+
+# Update contact using email
+contacts.upsert(
+  updated_contact.email,
+  email: '[email protected]',
+  fields: { field.merge_tag => 'Jane Doe' }
+)
+# => Contact.new(
+#      id: 1,
+#      email: '[email protected]',
+#      fields: { 'nickname' => 'Jane Doe' },
+#      list_ids: [1],
+#      status: 'subscribed',
+#      created_at: 1721212345,
+#      updated_at: 1721212355
+#    )
+updated_contact.newly_created? # => false
+
+# Remove contact from lists
+contacts.remove_from_lists(contact.id, [list.id])
+# => Contact.new(
+#      id: 1,
+#      email: '[email protected]',
+#      fields: { 'nickname' => 'Jane Doe' },
+#      list_ids: [],
+#      status: 'subscribed',
+#      created_at: 1721212345,
+#      updated_at: 1721212360
+#    )
+
+# Add contact to lists
+contacts.add_to_lists(contact.id, [list.id])
+# => Contact.new(
+#      id: 1,
+#      email: '[email protected]',
+#      fields: { 'nickname' => 'Jane Doe' },
+#      list_ids: [1],
+#      status: 'subscribed',
+#      created_at: 1721212345,
+#      updated_at: 1721212365
+#    )
+
+# Delete contact
+contacts.delete(contact.id)
+
+# Delete contact list
+contact_lists.delete(list.id)
+
+# Delete contact field
+contact_fields.delete(field.id)

lib/mailtrap.rb

@@ -5,6 +5,9 @@
 require_relative 'mailtrap/errors'
 require_relative 'mailtrap/version'
 require_relative 'mailtrap/email_templates_api'
+require_relative 'mailtrap/contacts_api'
+require_relative 'mailtrap/contact_lists_api'
+require_relative 'mailtrap/contact_fields_api'
 
 module Mailtrap
   # @!macro api_errors

lib/mailtrap/base_api.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  module BaseAPI
+    attr_reader :account_id, :client
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      attr_accessor :supported_options, :response_class
+    end
+
+    # @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 supported_options
+      self.class.supported_options
+    end
+
+    def response_class
+      self.class.response_class
+    end
+
+    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
+
+    def base_get(id)
+      response = client.get("#{base_path}/#{id}")
+      handle_response(response)
+    end
+
+    def base_create(options, supported_options_override = supported_options)
+      validate_options!(options, supported_options_override)
+      response = client.post(base_path, wrap_request(options))
+      handle_response(response)
+    end
+
+    def base_update(id, options, supported_options_override = supported_options)
+      validate_options!(options, supported_options_override)
+      response = client.patch("#{base_path}/#{id}", wrap_request(options))
+      handle_response(response)
+    end
+
+    def base_delete(id)
+      client.delete("#{base_path}/#{id}")
+    end
+
+    def base_list
+      response = client.get(base_path)
+      response.map { |item| handle_response(item) }
+    end
+
+    def handle_response(response)
+      build_entity(response, response_class)
+    end
+
+    def wrap_request(options)
+      options
+    end
+
+    def base_path
+      raise NotImplementedError, 'base_path must be implemented in the including class'
+    end
+  end
+end

lib/mailtrap/contact.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/220a54e31e5ca-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
+  Contact = Struct.new(
+    :id,
+    :email,
+    :fields,
+    :list_ids,
+    :status,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  ) do
+    def initialize(options)
+      @action = options[:action]
+      super(options.except(:action))
+    end
+
+    # @return [Boolean] Whether the contact was newly created
+    def newly_created?
+      @action != 'updated'
+    end
+
+    # @return [Hash] The contact attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

lib/mailtrap/contact_field.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact Field
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/33efe96c91dcc-get-all-contact-fields
+  # @attr_reader id [Integer] The contact field ID
+  # @attr_reader name [String] The name of the contact field (max 80 characters)
+  # @attr_reader data_type [String] The data type of the field
+  #   Allowed values: text, integer, float, boolean, date
+  # @attr_reader merge_tag [String] Personalize your campaigns by adding a merge tag.
+  #   This field will be replaced with unique contact details for each recipient (max 80 characters)
+  ContactField = Struct.new(:id, :name, :data_type, :merge_tag, keyword_init: true) do
+    # @return [Hash] The contact field attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

lib/mailtrap/contact_fields_api.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'contact_field'
+
+module Mailtrap
+  class ContactFieldsAPI
+    include BaseAPI
+
+    self.supported_options = %i[name data_type merge_tag]
+
+    self.response_class = ContactField
+
+    # Retrieves a specific contact field
+    # @param field_id [Integer] The contact field identifier
+    # @return [ContactField] Contact field object
+    # @!macro api_errors
+    def get(field_id)
+      base_get(field_id)
+    end
+
+    # Creates a new contact field
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The contact field name
+    # @option options [String] :data_type The data type of the field
+    # @option options [String] :merge_tag The merge tag of the field
+    # @return [ContactField] Created contact field object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing contact field
+    # @param field_id [Integer] The contact field ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The contact field name
+    # @option options [String] :merge_tag The merge tag of the field
+    # @return [ContactField] Updated contact field object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(field_id, options)
+      base_update(field_id, options, %i[name merge_tag])
+    end
+
+    # Deletes a contact field
+    # @param field_id [Integer] The contact field ID
+    # @return nil
+    # @!macro api_errors
+    def delete(field_id)
+      base_delete(field_id)
+    end
+
+    # Lists all contact fields for the account
+    # @return [Array<ContactField>] Array of contact field objects
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts/fields"
+    end
+  end
+end

lib/mailtrap/contact_list.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # 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
+  # @attr_reader name [String] The name of the contact list
+  ContactList = Struct.new(:id, :name, keyword_init: true) do
+    # @return [Hash] The contact list attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end