unisender-ruby 0.1.1 → 0.2.0

data/lib/unisender/configuration.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Immutable options; injected transports remain owned by the caller.
+  # rubocop:disable-next Metrics/ClassLength -- Owns the complete public configuration and resource lifetime.
+  class Configuration
+    DEFAULT_KEYS = %i[sender_name sender_email lang].freeze
+    TIMEOUT_KEYS = %i[open_timeout read_timeout write_timeout persistent].freeze
+    RETRY_KEYS = %i[max_retries max_elapsed].freeze
+    attr_reader :api_key, :language, :transport, :retry_policy, :message_defaults, :instrumentation, :rate_limiter,
+                :event_rate_limiter, :acceptance_instrumentation
+
+    # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- Keep immutable public options together.
+    def initialize(api_key:, language: :en, transport: nil, retry_policy: nil, open_timeout: nil,
+                   read_timeout: nil, write_timeout: nil, max_retries: nil, max_elapsed: nil,
+                   message_defaults: {}, instrumentation: nil, persistent: false, rate_limiter: nil,
+                   event_rate_limiter: nil, acceptance_instrumentation: nil)
+      @api_key, @language = credentials(api_key, language)
+      @message_defaults = defaults(message_defaults)
+      @instrumentation = instrumentation
+      @transport = build_transport(transport, open_timeout, read_timeout, write_timeout, persistent)
+      @retry_policy = build_retry(retry_policy, max_retries, max_elapsed)
+      initialize_resources(rate_limiter, transport, event_rate_limiter, acceptance_instrumentation)
+      @options = { api_key: @api_key, language: @language, transport:, retry_policy:, open_timeout:,
+                   read_timeout:, write_timeout:, max_retries:, max_elapsed:, message_defaults: @message_defaults,
+                   instrumentation:, persistent:, rate_limiter:, event_rate_limiter:,
+                   acceptance_instrumentation: }.freeze
+      freeze
+    end
+
+    def options_for(changes)
+      options = @options.dup
+      clear_alternative(options, changes, :transport, TIMEOUT_KEYS)
+      clear_alternative(options, changes, :retry_policy, RETRY_KEYS)
+      options.merge!(changes)
+      merge_defaults(options, changes)
+      options
+    end
+
+    def merge_defaults(options, changes)
+      return unless changes.key?(:message_defaults)
+
+      value = changes.fetch(:message_defaults)
+      case value
+      when Hash then options[:message_defaults] = @message_defaults.merge(normalize_defaults(value))
+      else raise ArgumentError, "Message defaults must be a hash"
+      end
+    end
+
+    def inspect
+      "#<Unisender::Configuration>"
+    end
+
+    def check_open!
+      @state.check_open!
+    end
+
+    def close
+      @state.close do
+        transport = @transport
+        if @owns_transport
+          case transport
+          when PersistentTransport then transport.close
+          end
+        end
+      end
+    end
+
+    private
+
+    def clear_alternative(options, changes, object, settings)
+      if changes.key?(object)
+        settings.each { |key| options.delete(key) }
+      elsif settings.any? { |key| changes.key?(key) }
+        options.delete(object)
+      end
+    end
+
+    def build_transport(transport, open_timeout, read_timeout, write_timeout, persistent)
+      validate_conflicts(transport, [open_timeout, read_timeout, write_timeout])
+      raise ArgumentError, "Persistent mode conflicts with an explicit transport" if transport && persistent
+
+      factory = persistent ? PersistentTransport : Transport
+      transport || factory.new(**timeout_options(open_timeout, read_timeout, write_timeout))
+    end
+
+    def initialize_resources(limiter, transport, event_limiter, acceptance_callback)
+      @rate_limiter = limiter
+      @event_rate_limiter = event_limiter
+      @acceptance_instrumentation = acceptance_callback
+      @owns_transport = case transport
+                        when nil then true
+                        else false
+                        end
+      @state = ClientState.new
+    end
+
+    def timeout_options(open_timeout, read_timeout, write_timeout)
+      defaults = { open_timeout: 5, read_timeout: 60, write_timeout: 30 }
+      defaults.merge({ open_timeout:, read_timeout:, write_timeout: }.compact)
+    end
+
+    def build_retry(policy, max_retries, max_elapsed)
+      validate_conflicts(policy, [max_retries, max_elapsed])
+      policy || RetryPolicy.new(max_retries: max_retries.nil? ? 0 : max_retries,
+                                max_elapsed: max_elapsed.nil? ? 60 : max_elapsed)
+    end
+
+    def credentials(key, language)
+      unless key.is_a?(String) && !key.strip.empty? && !key.match?(/[\r\n]/)
+        raise ArgumentError, "api_key must be a nonempty string without line breaks"
+      end
+      raise ArgumentError, "language must be en or ru" unless %w[en ru].include?(language.to_s)
+
+      [key.dup.freeze, language.to_s.freeze]
+    end
+
+    def validate_conflicts(object, settings)
+      return unless object && settings.any? { |value| !value.nil? }
+
+      raise ArgumentError, "Explicit objects cannot be combined with their configuration options"
+    end
+
+    def defaults(values)
+      normalize_defaults(values).compact.freeze
+    end
+
+    def normalize_defaults(values)
+      validate_default_keys(values)
+      names = values.keys.map(&:to_sym)
+      unless names.uniq == names && names.all? { |key| DEFAULT_KEYS.include?(key) }
+        raise ArgumentError, "Unknown or duplicate message default"
+      end
+
+      values.to_h { |key, value| [key.to_sym, default_value(value)] }
+    end
+
+    def validate_default_keys(values)
+      return if values.is_a?(Hash) && values.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+
+      raise ArgumentError, "Message defaults require string or symbol keys"
+    end
+
+    def default_value(value)
+      return nil if value.nil?
+      raise ArgumentError, "Message defaults must be strings or nil" unless value.is_a?(String)
+
+      value.dup.freeze
+    end
+  end
+end

data/lib/unisender/contact_records.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Email details returned by getContact.
+  class EmailContact < Record
+    def email
+      text!("email")
+    end
+
+    def status
+      text("status")
+    end
+
+    def availability
+      text("availability")
+    end
+
+    def added_at
+      text("added_at")
+    end
+
+    def last_send_datetime
+      text("last_send_datetime")
+    end
+
+    def last_delivery_datetime
+      text("last_delivery_datetime")
+    end
+
+    def last_read_datetime
+      text("last_read_datetime")
+    end
+
+    def last_click_datetime
+      text("last_click_datetime")
+    end
+
+    def rating
+      number("rating")
+    end
+
+    protected
+
+    def normalize
+      email
+      status
+      availability
+      added_at
+      last_send_datetime
+      last_delivery_datetime
+      last_read_datetime
+      last_click_datetime
+      rating
+    end
+  end
+
+  # Optional phone details returned by getContact.
+  class PhoneContact < Record
+    def phone
+      text!("phone")
+    end
+
+    def status
+      text("status")
+    end
+
+    def availability
+      text("availability")
+    end
+
+    def added_at
+      text("added_at")
+    end
+
+    protected
+
+    def normalize
+      phone
+      status
+      availability
+      added_at
+    end
+  end
+
+  # A contact's membership in one list.
+  class ContactList < IdentifierRecord
+    def status
+      text("status")
+    end
+
+    def added_at
+      text("added_at")
+    end
+
+    protected
+
+    def normalize
+      super
+      status
+      added_at
+    end
+  end
+
+  # Optional account details remain accessible through their original keys.
+  class Contact < Record
+    def email
+      value = self["email"]
+      return value if value.nil? || value.is_a?(String)
+      return child(EmailContact, value.to_h, "email") if value.is_a?(Record)
+
+      invalid!("email")
+    end
+
+    def email_address
+      value = email
+      value.is_a?(EmailContact) ? value.email : value
+    end
+
+    def phone
+      value = self["phone"]
+      return value if value.nil? || value.is_a?(String)
+      return child(PhoneContact, value.to_h, "phone") if value.is_a?(Record)
+
+      invalid!("phone")
+    end
+
+    def phone_number
+      value = phone
+      value.is_a?(PhoneContact) ? value.phone : value
+    end
+
+    def lists
+      value = self["lists"]
+      return nil if value.nil?
+
+      Outcomes.records(value, "lists").each_with_index.map do |item, index|
+        child(ContactList, item.to_h, "lists[#{index}]")
+      end.freeze
+    end
+
+    def fields
+      value = self["fields"]
+      return value if value.nil? || value.is_a?(Record)
+
+      invalid!("fields")
+    end
+
+    protected
+
+    def normalize
+      email
+      phone
+      lists
+      fields
+    end
+  end
+
+  # Contact details with transport metadata.
+  class ContactResponse < ObjectResponse
+    def email
+      result.email
+    end
+
+    def email_address
+      result.email_address
+    end
+
+    def phone
+      result.phone
+    end
+
+    def phone_number
+      result.phone_number
+    end
+
+    def lists
+      result.lists
+    end
+
+    def fields
+      result.fields
+    end
+  end
+
+  # Sender-domain fields retain upstream capitalization in key-based access.
+  class SenderDomain < Record
+    def domain
+      text!("Domain")
+    end
+
+    def status
+      text("Status")
+    end
+
+    def key
+      text("key")
+    end
+
+    protected
+
+    def normalize
+      domain
+      status
+      key
+    end
+  end
+
+  # A group is the unit yielded by sender-domain pagination.
+  class SenderDomainGroup < Record
+    def status
+      text("status")
+    end
+
+    def domains
+      Outcomes.records(self["domains"], "domains").each_with_index.map do |item, index|
+        child(SenderDomain, item.to_h, "domains[#{index}]")
+      end.freeze
+    end
+
+    protected
+
+    def normalize
+      status
+      invalid!("domains") unless self["domains"].is_a?(Array)
+      domains
+    end
+  end
+
+  # Dynamic field IDs remain string keys.
+  class ContactFields < Record
+    def field_values
+      value = self["fieldValues"]
+      return value if value.is_a?(Record)
+
+      invalid!("fieldValues")
+    end
+
+    protected
+
+    def normalize
+      field_values
+    end
+  end
+
+  # Dynamic contact values with transport metadata.
+  class ContactFieldsResponse < ObjectResponse
+    def field_values
+      result.field_values
+    end
+  end
+end

data/lib/unisender/diagnostic_urls.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Unisender
+  module Diagnostics
+    # Official operation pages; only recognized names can produce a link.
+    URLS = {
+      "createList" => "https://www.unisender.com/ru/support/api/contacts/createlist/",
+      "deleteList" => "https://www.unisender.com/ru/support/api/contacts/deletelist/",
+      "exclude" => "https://www.unisender.com/ru/support/api/contacts/exclude/",
+      "async/exportContacts" => "https://www.unisender.com/ru/support/api/contacts/exportcontacts/",
+      "getContactCount" => "https://www.unisender.com/ru/support/api/contacts/getcontactcount/",
+      "getLists" => "https://www.unisender.com/ru/support/api/contacts/getlists/",
+      "getTotalContactsCount" => "https://www.unisender.com/ru/support/api/contacts/gettotalcontactscount/",
+      "importContacts" => "https://www.unisender.com/ru/support/api/contacts/importcontacts/",
+      "subscribe" => "https://www.unisender.com/ru/support/api/contacts/subscribe/",
+      "updateList" => "https://www.unisender.com/ru/support/api/contacts/updatelist/",
+      "isContactInLists" => "https://www.unisender.com/ru/support/api/contacts/iscontactinlists/",
+      "getContact" => "https://www.unisender.com/ru/support/api/contacts/getcontact/",
+      "unsubscribe" => "https://www.unisender.com/ru/support/api/contacts/unsubscribe/",
+      "cancelCampaign" => "https://www.unisender.com/ru/support/api/messages/cancel-campaign/",
+      "checkEmail" => "https://www.unisender.com/ru/support/api/messages/check-email/",
+      "checkSms" => "https://www.unisender.com/ru/support/api/messages/check-sms/",
+      "createCampaign" => "https://www.unisender.com/ru/support/api/messages/createcampaign/",
+      "createEmailMessage" => "https://www.unisender.com/ru/support/api/messages/createemailmessage/",
+      "createSmsMessage" => "https://www.unisender.com/ru/support/api/messages/createsmsmessage/",
+      "deleteMessage" => "https://www.unisender.com/ru/support/api/messages/deletemessage/",
+      "getActualMessageVersion" => "https://www.unisender.com/ru/support/api/messages/get-actual-message-version/",
+      "getWebVersion" => "https://www.unisender.com/ru/support/api/messages/getwebversion/",
+      "sendEmail" => "https://www.unisender.com/ru/support/api/messages/sendemail/",
+      "sendSms" => "https://www.unisender.com/ru/support/api/messages/sendsms/",
+      "sendTestEmail" => "https://www.unisender.com/ru/support/api/messages/sendtestemail/",
+      "updateEmailMessage" => "https://www.unisender.com/ru/support/api/messages/updateemailmessage/",
+      "updateOptInEmail" => "https://www.unisender.com/ru/support/api/messages/updateoptinemail/",
+      "getSenderDomainList" => "https://www.unisender.com/ru/support/api/messages/getsenderdomainlist/",
+      "getCampaignCommonStats" => "https://www.unisender.com/ru/support/api/statistics/get-campaign-common-stats/",
+      "async/getCampaignDeliveryStats" => "https://www.unisender.com/ru/support/api/statistics/getcampaigndeliverystats/",
+      "getCampaignStatus" => "https://www.unisender.com/ru/support/api/statistics/getcampaignstatus/",
+      "getMessages" => "https://www.unisender.com/ru/support/api/statistics/getmessages/",
+      "getVisitedLinks" => "https://www.unisender.com/ru/support/api/statistics/getvisitedlinks/",
+      "listMessages" => "https://www.unisender.com/ru/support/api/statistics/listmessages/",
+      "getCampaigns" => "https://www.unisender.com/ru/support/api/statistics/getcampaigns/",
+      "getMessage" => "https://www.unisender.com/ru/support/api/statistics/getmessage/",
+      "async/getTaskResult" => "https://www.unisender.com/ru/support/api/statistics/../contacts/exportcontacts/",
+      "createEmailTemplate" => "https://www.unisender.com/ru/support/api/templates/createemailtemplate/",
+      "deleteTemplate" => "https://www.unisender.com/ru/support/api/templates/deletetemplate/",
+      "getTemplate" => "https://www.unisender.com/ru/support/api/templates/gettemplate/",
+      "getTemplates" => "https://www.unisender.com/ru/support/api/templates/gettemplates/",
+      "listTemplates" => "https://www.unisender.com/ru/support/api/templates/listtemplates/",
+      "updateEmailTemplate" => "https://www.unisender.com/ru/support/api/templates/updateemailtemplate/",
+      "createField" => "https://www.unisender.com/ru/support/api/inputs/createfield/",
+      "deleteField" => "https://www.unisender.com/ru/support/api/inputs/deletefield/",
+      "deleteTag" => "https://www.unisender.com/ru/support/api/inputs/deletetag/",
+      "getFields" => "https://www.unisender.com/ru/support/api/inputs/getfields/",
+      "getTags" => "https://www.unisender.com/ru/support/api/inputs/gettags/",
+      "updateField" => "https://www.unisender.com/ru/support/api/inputs/updatefield/",
+      "getContactFieldValues" => "https://www.unisender.com/ru/support/api/inputs/getcontactfieldvalues/",
+      "createSubscriberNote" => "https://www.unisender.com/ru/support/api/notes/createsubscibernote/",
+      "updateSubscriberNote" => "https://www.unisender.com/ru/support/api/notes/updatesubcribernote/",
+      "deleteSubscriberNote" => "https://www.unisender.com/ru/support/api/notes/deletesubscribernote/",
+      "getSubscriberNote" => "https://www.unisender.com/ru/support/api/notes/getsubscribernote/",
+      "getSubscriberNotes" => "https://www.unisender.com/ru/support/api/notes/getsubscribernotes/",
+      "setHook" => "https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/",
+      "listHooks" => "https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/",
+      "removeHook" => "https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/",
+      "track_events" => "https://www.unisender.com/ru/support/api/event-tracking-api/"
+    }.freeze
+  end
+end

data/lib/unisender/diagnostics.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Safe error metadata excludes payload values and arbitrary exception text.
+  module Diagnostics
+    # @type var types: Hash[Module, String]
+    types = { String => "String", Integer => "Integer", Float => "Float", Symbol => "Symbol",
+              Array => "Array", Hash => "Hash", NilClass => "NilClass",
+              TrueClass => "Boolean", FalseClass => "Boolean" }
+    TYPES = types.freeze
+    FIELDS = (OperationContracts::DEFINITIONS.values.flat_map { |definition| definition.last.keys } +
+              %w[parameters max_bytes batch_size retention filename email_list_ids phone_list_ids
+                 email_subscribe_times phone_subscribe_times tags]).uniq.freeze
+
+    def self.input_path(path)
+      root = path.split(/[.\[]/, 2).first.to_s
+      return "parameters" unless FIELDS.include?(root)
+
+      path.split(/\.(?![^\[]*\])/, -1).map { |segment| path_segment(segment) }.join(".")
+    end
+
+    def self.path_segment(segment)
+      name = segment.split("[", 2).first.to_s
+      return "*" unless FIELDS.include?(name)
+
+      suffix = segment.delete_prefix(name)
+      return "#{name}[*]" unless suffix.match?(/\A(?:\[[^\]]*\])*\z/)
+
+      indices = suffix.split("]").map { |part| part.match?(/\A\[\d+\z/) ? "#{part}]" : "[*]" }
+      name + indices.join
+    end
+
+    def self.type_name(value)
+      TYPES.each { |type, name| return name if value.is_a?(type) }
+      "Object"
+    end
+
+    def self.for_error(error)
+      values = common_fields(error)
+      values.merge!(error.is_a?(ValidationError) ? validation_fields(error) : error_fields(error))
+      cause = underlying(error) if error.is_a?(Error)
+      values = for_error(cause).merge(values) if cause
+      values.compact.freeze
+    end
+
+    def self.common_fields(error)
+      { operation: error.operation, category: error.category.to_s,
+        documentation_url: URLS[error.operation.to_s] }.compact
+    end
+
+    def self.validation_fields(error)
+      { path: error.path, code: error.code.to_s, expected_type: error.expected_type, actual_type: error.actual_type }
+    end
+
+    def self.error_fields(error)
+      values = context_fields(error)
+      values[:code] = error.safe_code if error.is_a?(APIError)
+      values.merge!(batch_fields(error)) if error.is_a?(BatchError)
+      if error.is_a?(InvalidResponseError)
+        values.merge!(path: error.path, expected_type: error.expected_type, actual_type: error.actual_type)
+      end
+      values.compact
+    end
+
+    def self.context_fields(error)
+      { http_status: error.http_status, request_id: error.request_id, task_uuid: error.task_uuid,
+        next_offset: error.next_offset, completed_pages: error.completed_pages, bytes_written: error.bytes_written }
+    end
+
+    def self.batch_fields(error)
+      { completed_batches: error.completed_responses.size,
+        failed_from: error.failed_range.begin, failed_to: error.failed_range.end }
+    end
+
+    def self.underlying(error)
+      case error
+      when BatchError, CampaignWorkflowError
+        cause = error.error
+        cause if cause.is_a?(Error) || cause.is_a?(ValidationError)
+      end
+    end
+  end
+end

data/lib/unisender/download_target.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "socket"
+require "timeout"
+
+module Unisender
+  # Resolves once and returns a public address for a verified HTTPS connection.
+  class DownloadTarget
+    GLOBAL_V6 = IPAddr.new("2000::/3").freeze
+    # Conservative exclusions based on the IANA special-purpose address registries.
+    # https://www.iana.org/assignments/iana-ipv6-special-registry/
+    # https://www.iana.org/assignments/iana-ipv4-special-registry/
+    BLOCKED = %w[
+      0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 169.254.0.0/16 172.16.0.0/12
+      192.0.0.0/24 192.0.2.0/24 192.88.99.0/24 192.168.0.0/16 198.18.0.0/15 198.51.100.0/24 203.0.113.0/24
+      224.0.0.0/4 240.0.0.0/4 ::/128 ::1/128 fc00::/7 fe80::/10 ff00::/8 2001:db8::/32
+      2001::/23 2002::/16 3fff::/20
+    ].map { |range| IPAddr.new(range) }.freeze
+
+    def initialize(timeout:, resolver: nil)
+      @timeout = timeout
+      @resolver = resolver || ->(host) { Addrinfo.getaddrinfo(host, 443, nil, :STREAM).map(&:ip_address).uniq }
+    end
+
+    def resolve(url)
+      uri = validated_uri(url)
+      addresses = resolved_addresses(uri.hostname.to_s)
+      [uri, addresses.fetch(0)]
+    rescue URI::InvalidURIError, IPAddr::InvalidAddressError
+      raise DownloadError.new(reason: :invalid_url), cause: nil
+    end
+
+    private
+
+    def validated_uri(url)
+      uri = URI(url)
+      unless uri.scheme == "https" && uri.port == 443 && uri.hostname && !uri.userinfo
+        raise DownloadError.new(reason: :invalid_url)
+      end
+
+      uri
+    end
+
+    def resolved_addresses(host)
+      addresses = Timeout.timeout(@timeout) { @resolver.call(host) }
+      if addresses.empty? || addresses.any? { |address| blocked?(address) }
+        raise DownloadError.new(reason: :blocked_destination)
+      end
+
+      addresses
+    end
+
+    def blocked?(address)
+      ip = IPAddr.new(address).native
+      return true if ip.ipv6? && !GLOBAL_V6.include?(ip)
+
+      BLOCKED.any? { |range| range.include?(ip) }
+    end
+  end
+end

data/lib/unisender/download_transfer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Counts only writes acknowledged by the caller-owned destination.
+  class DownloadTransfer
+    attr_reader :bytes_written
+
+    def initialize(io, max_bytes, execution: nil)
+      raise ArgumentError, "max_bytes must be a positive integer" unless max_bytes.is_a?(Integer) && max_bytes.positive?
+
+      @io = io
+      @max_bytes = max_bytes
+      @bytes_written = 0
+      @execution = execution
+    end
+
+    def write(chunk)
+      @execution&.check!
+      raise DownloadError.new(reason: :too_large) if @bytes_written + chunk.bytesize > @max_bytes
+
+      copy_chunk(chunk)
+    rescue DownloadError, CancelledError, DeadlineExceededError
+      raise
+    rescue StandardError
+      raise DownloadError.new(reason: :write_failed), cause: nil
+    end
+
+    private
+
+    def copy_chunk(chunk)
+      offset = 0
+      while offset < chunk.bytesize
+        @execution&.check!
+        part = chunk.byteslice(offset..).to_s
+        written = @io.write(part)
+        raise DownloadError.new(reason: :write_failed) unless written.positive? && written <= part.bytesize
+
+        offset += written
+        @bytes_written += written
+      end
+    end
+  end
+end