unisender-ruby 0.1.0

data/examples/campaign.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Requires UNISENDER_API_KEY, UNISENDER_LIST_ID, and UNISENDER_SENDER_EMAIL.
+# Sends a campaign to the list. Use a verified sender and a list of consenting test recipients.
+require "unisender"
+
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+message = client.create_email_message(
+  sender_name: "Example", sender_email: ENV.fetch("UNISENDER_SENDER_EMAIL"),
+  list_id: ENV.fetch("UNISENDER_LIST_ID"), subject: "Product news", body: "<p>Hello</p>"
+)
+campaign = client.create_campaign(message_id: message.result.fetch("message_id"))
+puts campaign.result.fetch("campaign_id")

data/examples/check_connection.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Requires UNISENDER_API_KEY. Reads lists without printing account data.
+require "unisender"
+
+api_key = ENV.fetch("UNISENDER_API_KEY", nil)
+abort "Set UNISENDER_API_KEY before running this example." if api_key.nil? || api_key.strip.empty?
+
+begin
+  client = Unisender::Client.new(api_key:)
+  response = client.get_lists
+  puts "Connected to UniSender: HTTP #{response.status}, #{response.result.size} list(s)."
+rescue ArgumentError, Unisender::Error => e
+  warn e.message
+  exit 1
+end

data/examples/events.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Requires UNISENDER_API_KEY and UNISENDER_CONTACT_EMAIL.
+# Records an event and can trigger account automation.
+require "unisender"
+
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+begin
+  client.track_events_in_batches(events: [
+                                   { name: "purchase", email: ENV.fetch("UNISENDER_CONTACT_EMAIL"), total: 1200,
+                                     currency: "RUB" }
+                                 ]).each { |response| puts "Recorded batch: HTTP #{response.status}" }
+rescue Unisender::BatchError => e
+  warn "Review events #{e.failed_range}; completed batches: #{e.completed_responses.size}"
+  failure = e.error
+  if failure.is_a?(Unisender::EventError) && failure.possibly_partially_accepted?
+    warn "Valid events may already be accepted. Inspect failure.details privately before retrying."
+  end
+  warn failure.message
+end

data/examples/export.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Requires UNISENDER_API_KEY and UNISENDER_LIST_ID. Starts an export job.
+# The returned download URL grants access to contact data; keep it private.
+require "unisender"
+
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+job = client.export_contacts(list_id: ENV.fetch("UNISENDER_LIST_ID"))
+completed = client.wait_for_task(task_uuid: job.result.fetch("task_uuid"))
+download_url = completed.result.fetch("file_to_download")
+puts "Export ready at host: #{URI(download_url).host}"

data/examples/import.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Requires UNISENDER_API_KEY and UNISENDER_CONTACT_EMAIL. Changes contacts.
+require "unisender"
+
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+begin
+  client.import_contacts_in_batches(
+    field_names: %w[email Name], data: [[ENV.fetch("UNISENDER_CONTACT_EMAIL"), "Example"]]
+  ).each { |response| puts "Imported batch: HTTP #{response.status}" }
+rescue Unisender::BatchError => e
+  warn "Completed batches: #{e.completed_responses.size}; review rows #{e.failed_range}"
+  if e.error.is_a?(Unisender::PartialFailure)
+    warn "Some rows in the failed batch were accepted. Inspect error.error.response.result privately."
+  end
+  warn e.error.message
+  # Stop here. Reconcile accepted rows before building a new input; never replay all rows blindly.
+end

data/examples/offline.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# No credentials or network access required.
+require "unisender"
+
+# Records requests and returns one deterministic response without a socket.
+class FakeTransport
+  attr_reader :requests
+
+  def initialize
+    @requests = []
+  end
+
+  def post(uri, headers:, body:)
+    @requests << { uri:, headers:, body: }
+    Unisender::HTTPResponse.new(
+      status: 200, headers: { "x-request-id" => "offline-example" },
+      body: '{"result":[{"id":42,"title":"Product news"}]}'
+    )
+  end
+end
+
+transport = FakeTransport.new
+client = Unisender::Client.new(api_key: "test-key", transport:)
+client.get_lists.result.each { |list| puts list.fetch("title") }
+puts "Requests: #{transport.requests.size}"

data/examples/quickstart.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "unisender"
+
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+client.get_lists.result.each { |list| puts list.fetch("title") }

data/examples/subscribe.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Requires UNISENDER_API_KEY, UNISENDER_LIST_ID, and UNISENDER_CONTACT_EMAIL.
+# Changes the account and sends a subscription confirmation email.
+require "unisender"
+
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+response = client.subscribe(
+  list_ids: [ENV.fetch("UNISENDER_LIST_ID")],
+  fields: { email: ENV.fetch("UNISENDER_CONTACT_EMAIL") }
+)
+puts response.result.fetch("person_id")

data/lib/unisender/batches.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Executes one batch at a time; a failure never replays previous batches.
+  module Batches
+    def self.each(items, size, maximum, &operation)
+      raise ArgumentError, "Invalid batch_size" unless size.is_a?(Integer) && size.positive? && size <= maximum
+
+      Enumerator.new do |output|
+        # @type var completed: Array[Response]
+        completed = []
+        items.each_slice(size).with_index do |batch, index|
+          response = execute(batch, index * size, completed, &operation)
+          completed << response
+          output << response
+        end
+      end
+    end
+
+    def self.execute(batch, offset, completed)
+      response = yield batch
+      result = response.result
+      raise PartialFailure, response if result.is_a?(Hash) && result.fetch("invalid", 0).to_s.to_i.positive?
+
+      response
+    rescue Error, ArgumentError => e
+      raise BatchError.new(completed_responses: completed, failed_range: offset...(offset + batch.size), error: e),
+            cause: nil
+    end
+  end
+end

data/lib/unisender/client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Synchronous client for the documented UniSender API.
+  class Client
+    RESERVED_PARAMETERS = %w[api_key format].freeze
+
+    def initialize(api_key:, transport: Transport.new, language: :en, retry_policy: RetryPolicy.new)
+      unless api_key.is_a?(String) && !api_key.strip.empty? && !api_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)
+
+      @api_key = api_key.dup.freeze
+      @language = language.to_s.dup.freeze
+      @transport = transport
+      @retry_policy = retry_policy
+      freeze
+    end
+
+    def request(method, params: {})
+      validate_request(method, params)
+      uri = URI("https://api.unisender.com/#{@language}/api/#{method}")
+      headers = { "Content-Type" => "application/x-www-form-urlencoded; charset=UTF-8" }
+      body = Form.encode(params.merge("api_key" => @api_key, "format" => "json"))
+      @retry_policy.call(method) do
+        response = @transport.post(uri, headers:, body:)
+        Protocol.parse(response, method:)
+      end
+    rescue Error => e
+      raise e.with_operation(method), cause: nil
+    end
+
+    def inspect
+      "#<Unisender::Client>"
+    end
+
+    private
+
+    def validate_request(method, params)
+      raise ArgumentError, "Invalid API method name" unless method.match?(%r{\A(?:async/)?[A-Za-z][A-Za-z0-9]*\z})
+      return unless params.keys.any? { |key| RESERVED_PARAMETERS.include?(key.to_s) }
+
+      raise ArgumentError, "api_key and format are managed by the client"
+    end
+
+    # The wire response stays JSON; each named operation declares the documented result type.
+    # @type method invoke: (String, params, ?required: Array[String], ?comma: Array[String]) -> Response[json]
+    def invoke(method, params, required: [], comma: [])
+      Validation.required!(params, required)
+      Validation.operation!(method, params)
+      comma.each do |name|
+        value = params[name.to_sym]
+        params[name.to_sym] = Validation.comma_list(value) if value.is_a?(Array)
+      end
+      request(method, params:)
+    end
+  end
+end

data/lib/unisender/errors.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Base class for client and service failures.
+  class Error < StandardError
+    OPERATIONS = %w[
+      createList deleteList exclude async/exportContacts getContactCount getLists getTotalContactsCount
+      importContacts subscribe updateList isContactInLists getContact unsubscribe cancelCampaign
+      checkEmail checkSms createCampaign createEmailMessage createSmsMessage deleteMessage
+      getActualMessageVersion getWebVersion sendEmail sendSms sendTestEmail updateEmailMessage
+      updateOptInEmail getSenderDomainList getCampaignCommonStats async/getCampaignDeliveryStats
+      getCampaignStatus getMessages getVisitedLinks listMessages getCampaigns getMessage async/getTaskResult
+      createEmailTemplate deleteTemplate getTemplate getTemplates listTemplates updateEmailTemplate
+      createField deleteField deleteTag getFields getTags updateField getContactFieldValues
+      createSubscriberNote updateSubscriberNote deleteSubscriberNote getSubscriberNote getSubscriberNotes
+      track_events
+    ].freeze
+    private_constant :OPERATIONS
+
+    attr_reader :operation
+
+    def with_operation(operation)
+      @operation = OPERATIONS.include?(operation) ? operation.dup.freeze : nil
+      self
+    end
+
+    def to_s
+      "UniSender #{@operation || 'request'} failed: #{super}"
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+  end
+
+  # Main API failure, including failures returned with HTTP 200.
+  class APIError < Error
+    # https://www.unisender.com/ru/support/api/common/api-errors/
+    SAFE_CODES = %w[
+      unspecified invalid_api_key access_denied unknown_method invalid_arg not_enough_money retry_later
+      api_call_limit_exceeded_for_api_key api_call_limit_exceeded_for_ip
+    ].freeze
+    private_constant :SAFE_CODES
+
+    attr_reader :response, :code, :details
+
+    def initialize(response)
+      @response = response
+      @code = response.data["code"]
+      @details = response.data["error"]
+      super(SAFE_CODES.include?(@code) ? @code.to_s : "API error")
+    end
+  end
+
+  # Non-success HTTP response, including redirects.
+  class HTTPError < Error
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super("HTTP #{response.status}")
+    end
+  end
+
+  class InvalidResponseError < Error; end
+
+  # Network or TLS failure with no complete HTTP response.
+  class TransportError < Error
+    def initialize(message, retryable: false)
+      @retryable = retryable
+      super(message)
+    end
+
+    def retryable?
+      @retryable
+    end
+  end
+
+  class TimeoutError < TransportError; end
+
+  # A failed event request can still have accepted some events (HTTP 400).
+  class EventError < HTTPError
+    def code
+      response.data["code"]
+    end
+
+    def details
+      response.data.fetch("details", response.data["error"])
+    end
+
+    def possibly_partially_accepted?
+      response.status == 400
+    end
+  end
+
+  # Carries the completed batches and the range whose outcome needs inspection.
+  class BatchError < Error
+    attr_reader :completed_responses, :failed_range, :error
+
+    def initialize(completed_responses:, failed_range:, error:)
+      @completed_responses = completed_responses.dup.freeze
+      @failed_range = failed_range.freeze
+      @error = error
+      super("UniSender batch failed; inspect the completed responses and failed range")
+    end
+  end
+
+  class PaginationError < Error; end
+
+  # The API accepted the import request but rejected some records.
+  class PartialFailure < Error
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super("UniSender rejected part of the batch")
+    end
+  end
+
+  # Includes the last response for an unexpected or failed asynchronous task state.
+  class TaskError < Error
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super("UniSender task returned an unexpected state")
+    end
+  end
+end

data/lib/unisender/event_payload.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Event Tracking uses JSON with its own batch and payload limits.
+  module EventPayload
+    def self.encode(events)
+      raise ArgumentError, "Expected 1 to 25 events" unless (1..25).cover?(events.size)
+
+      normalized = events.map { |event| validate(normalize(event, 0)) }
+      body = JSON.generate({ "events" => normalized })
+      raise ArgumentError, "Event payload exceeds 130 KB" if body.bytesize > 130 * 1024
+
+      body
+    rescue EncodingError, JSON::GeneratorError
+      raise ArgumentError, "Events must contain valid JSON values and UTF-8 text", cause: nil
+    end
+
+    def self.validate(event)
+      raise ArgumentError, "Each event must be an object" unless event.is_a?(Hash)
+      raise ArgumentError, "Each event may have at most 25 fields" if event.size > 25
+
+      validate_name(event["name"])
+      validate_email(event["email"])
+      event
+    end
+
+    def self.validate_name(name)
+      return if name.is_a?(String) && (1..40).cover?(name.size)
+
+      raise ArgumentError, "Event name must contain 1 to 40 characters"
+    end
+
+    def self.validate_email(email)
+      return if email.is_a?(String) && email.ascii_only? && email.match?(/\A[^\s@]+@[^\s@]+\z/)
+
+      raise ArgumentError, "Event email must be an ASCII email address"
+    end
+
+    def self.normalize(value, depth)
+      raise ArgumentError, "Events are nested too deeply" if depth > 32
+
+      case value
+      when Hash then normalize_hash(value, depth)
+      when Array then value.map { |item| normalize(item, depth + 1) }
+      when String then value.encode(Encoding::UTF_8)
+      when Integer, Float, true, false, nil then value
+      else raise ArgumentError, "Unsupported JSON value"
+      end
+    end
+
+    def self.normalize_hash(value, depth)
+      # @type var result: Hash[String, json]
+      result = {}
+      value.each do |key, item|
+        name = key.to_s.encode(Encoding::UTF_8)
+        raise ArgumentError, "Duplicate event field names" if result.key?(name)
+
+        result[name] = normalize(item, depth + 1)
+      end
+      result
+    end
+  end
+end

data/lib/unisender/events.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Unisender
+  # JSON Event Tracking endpoint.
+  class Client
+    def track_events(events:)
+      body = EventPayload.encode(events)
+      headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{@api_key}" }
+      http = @transport.post(URI("https://event.unisender.com/v1/events/"), headers:, body:)
+      response = Response.new(data: Protocol.decode(http), status: http.status, headers: http.headers)
+      raise EventError, response, cause: nil unless (200..299).cover?(http.status)
+      raise InvalidResponseError, "Missing event success status", cause: nil unless response.data["success"] == true
+
+      response # : Response[event_accepted]
+    rescue Error => e
+      raise e.with_operation("track_events"), cause: nil
+    end
+  end
+end

data/lib/unisender/form.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Unisender
+  # UniSender accepts indexed form fields, not JSON, including for attachments.
+  module Form
+    def self.encode(params)
+      URI.encode_www_form(pairs(params, nil, 0))
+    rescue EncodingError
+      raise ArgumentError, "Parameters must contain valid UTF-8 text", cause: nil
+    end
+
+    def self.pairs(value, prefix, depth)
+      raise ArgumentError, "Parameters are nested too deeply" if depth > 32
+
+      case value
+      when Hash
+        hash_pairs(value, prefix, depth)
+      when Array
+        value.each_with_index.flat_map { |item, index| pairs(item, "#{prefix}[#{index}]", depth + 1) }
+      else
+        [[prefix.to_s, scalar(value, prefix.to_s)]]
+      end
+    end
+
+    def self.hash_pairs(value, prefix, depth)
+      keys = value.keys.map(&:to_s)
+      raise ArgumentError, "Duplicate parameter names" unless keys.uniq.size == keys.size
+
+      value.flat_map do |key, item|
+        name = key.to_s.encode(Encoding::UTF_8)
+        raise ArgumentError, "Parameter names cannot contain brackets" if name.match?(/[\[\]]/)
+        next [] if item.nil?
+
+        pairs(item, prefix ? "#{prefix}[#{name}]" : name, depth + 1)
+      end
+    end
+
+    def self.scalar(value, name)
+      case value
+      when String
+        name.start_with?("attachments[") ? value.b : text(value)
+      when true then "1"
+      when false then "0"
+      when nil then ""
+      else numeric(value)
+      end
+    end
+
+    def self.text(value)
+      raise ArgumentError, "Parameters must contain valid UTF-8 text" unless value.valid_encoding?
+
+      value.encode(Encoding::UTF_8)
+    end
+
+    def self.numeric(value)
+      case value
+      when Integer then value.to_s
+      when Float
+        raise ArgumentError, "Numeric parameters must be finite" unless value.finite?
+
+        value.to_s
+      else
+        raise ArgumentError, "Unsupported parameter type"
+      end
+    end
+  end
+end

data/lib/unisender/helpers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Explicit helpers for multiple requests.
+  class Client
+    def each_page(method, page_size: 100, max_pages: 1000, **params)
+      Pagination.new(self, method, page_size, max_pages, params).each
+    end
+
+    # rubocop:disable-next Metrics/ParameterLists -- Includes the documented import options.
+    def import_contacts_in_batches(field_names:, data:, batch_size: 500, overwrite_tags: nil,
+                                   overwrite_lists: nil, telegram_bot_channel_id: nil)
+      Batches.each(data, batch_size, 500) do |batch|
+        import_contacts(field_names:, data: batch, overwrite_tags:, overwrite_lists:, telegram_bot_channel_id:)
+      end
+    end
+
+    def track_events_in_batches(events:, batch_size: 25)
+      Batches.each(events, batch_size, 25) { |batch| track_events(events: batch) }
+    end
+
+    def wait_for_task(task_uuid:, interval: 1, timeout: 60, clock: nil, sleeper: nil)
+      clock ||= -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      sleeper ||= ->(delay) { sleep(delay) }
+      TaskWaiter.new(self, clock:, sleeper:).call(task_uuid, interval, timeout) # : Response[task_completed]
+    end
+  end
+end

data/lib/unisender/operations/contacts_1.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Contacts operations from the official UniSender API.
+  class Client
+    # https://www.unisender.com/ru/support/api/contacts/createlist/
+    def create_list(title:, before_subscribe_url: nil, after_subscribe_url: nil, sub_user_rights: nil)
+      params = { title:, before_subscribe_url:, after_subscribe_url:, sub_user_rights: }
+      invoke("createList", params, required: %w[title])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/deletelist/
+    def delete_list(list_id:)
+      params = { list_id: }
+      invoke("deleteList", params, required: %w[list_id])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/exclude/
+    def exclude(contact_type:, contact:, list_ids: nil)
+      params = { contact_type:, contact:, list_ids: }
+      invoke("exclude", params, required: %w[contact_type contact], comma: %w[list_ids])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/exportcontacts/
+    # rubocop:disable-next Metrics/ParameterLists -- Mirrors the documented operation.
+    def export_contacts(notify_url: nil, list_id: nil, field_names: nil, email: nil, phone: nil, tag: nil,
+                        email_status: nil, phone_status: nil, contact_status: nil)
+      params = { notify_url:, list_id:, field_names:, email:, phone:, tag:, email_status:, phone_status:,
+                 contact_status: }
+      invoke("async/exportContacts", params)
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/getcontactcount/
+    def get_contact_count(list_id:, params:)
+      params = { list_id:, params: }
+      invoke("getContactCount", params, required: %w[list_id params])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/getlists/
+    # rubocop:disable-next Naming/AccessorMethodName -- Mirrors the documented operation.
+    def get_lists
+      invoke("getLists", {})
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/gettotalcontactscount/
+    def get_total_contacts_count(login:)
+      params = { login: }
+      invoke("getTotalContactsCount", params, required: %w[login])
+    end
+  end
+end

data/lib/unisender/operations/contacts_2.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Contacts operations from the official UniSender API.
+  class Client
+    # https://www.unisender.com/ru/support/api/contacts/importcontacts/
+    def import_contacts(field_names:, data:, overwrite_tags: nil, overwrite_lists: nil,
+                        telegram_bot_channel_id: nil)
+      params = { field_names:, data:, overwrite_tags:, overwrite_lists:, telegram_bot_channel_id: }
+      invoke("importContacts", params, required: %w[field_names data])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/subscribe/
+    def subscribe(list_ids:, fields:, tags: nil, double_optin: nil, overwrite: nil)
+      params = { list_ids:, fields:, tags:, double_optin:, overwrite: }
+      invoke("subscribe", params, required: %w[list_ids fields], comma: %w[list_ids tags])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/updatelist/
+    def update_list(list_id:, title:, before_subscribe_url: nil, after_subscribe_url: nil, sub_user_rights: nil)
+      params = { list_id:, title:, before_subscribe_url:, after_subscribe_url:, sub_user_rights: }
+      invoke("updateList", params, required: %w[list_id title])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/iscontactinlists/
+    # rubocop:disable-next Naming/PredicatePrefix -- Mirrors the documented operation.
+    def is_contact_in_lists(email:, list_ids:, condition:)
+      params = { email:, list_ids:, condition: }
+      invoke("isContactInLists", params, required: %w[email list_ids condition], comma: %w[list_ids])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/getcontact/
+    def get_contact(email:, include_lists: nil, include_fields: nil, include_details: nil)
+      params = { email:, include_lists:, include_fields:, include_details: }
+      invoke("getContact", params, required: %w[email])
+    end
+
+    # https://www.unisender.com/ru/support/api/contacts/unsubscribe/
+    def unsubscribe(contact_type:, contact:, list_ids: nil)
+      params = { contact_type:, contact:, list_ids: }
+      invoke("unsubscribe", params, required: %w[contact_type contact], comma: %w[list_ids])
+    end
+  end
+end