unisender-ruby 0.1.1 → 0.2.0

data/lib/unisender/response.rb

@@ -21,27 +21,30 @@ module Unisender
     empty = []
     EMPTY_WARNINGS = empty.freeze
 
-    attr_reader :data, :status, :headers
+    attr_reader :data, :http_status, :headers, :result
 
-    def initialize(data:, status:, headers:)
+    def initialize(data:, status:, headers:, result: nil)
       @data = immutable_hash(data)
-      @status = status
+      @http_status = status
+      @result = result.nil? ? @data.fetch("result", @data) : result
       @headers = headers.to_h { |key, value| [key.dup.freeze, value.dup.freeze] }.freeze
       freeze
     end
 
-    # The parser retains JSON; named operation signatures describe its upstream shape.
-    # @type method result: () -> json
-    def result
-      @data.fetch("result", @data)
-    end
-
     def warnings
       @data.fetch("warnings", EMPTY_WARNINGS)
     end
 
+    def as_json(options = nil)
+      Serialization.payload(@result, options)
+    end
+
+    def to_json(state = nil)
+      Serialization.json(@result, state)
+    end
+
     def inspect
-      "#<Unisender::Response status=#{@status}>"
+      "#<Unisender::Response http_status=#{@http_status}>"
     end
 
     private

data/lib/unisender/result_registry.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Result classes for named operations.
+  module Results
+    # @type var models: Hash[String, [singleton(Record), singleton(ObjectResponse)]]
+    models = {
+      "createList" => [IdentifierRecord, IdentifierRecordResponse],
+      "deleteList" => [Record, ObjectResponse],
+      "exclude" => [Record, ObjectResponse],
+      "async/exportContacts" => [TaskResult, TaskResultResponse],
+      "getContactCount" => [ContactCount, ContactCountResponse],
+      "getLists" => [List, ListResponse],
+      "getTotalContactsCount" => [TotalContacts, TotalContactsResponse],
+      "importContacts" => [ImportResult, ImportResponse],
+      "subscribe" => [Subscription, SubscriptionResponse],
+      "updateList" => [Record, ObjectResponse],
+      "getContact" => [Contact, ContactResponse],
+      "unsubscribe" => [Record, ObjectResponse],
+      "cancelCampaign" => [Record, ObjectResponse],
+      "checkEmail" => [EmailDelivery, ObjectResponse],
+      "checkSms" => [Status, StatusResponse],
+      "createCampaign" => [CampaignCreated, CampaignCreatedResponse],
+      "createEmailMessage" => [MessageCreated, MessageCreatedResponse],
+      "createSmsMessage" => [MessageCreated, MessageCreatedResponse],
+      "deleteMessage" => [Record, ObjectResponse],
+      "getActualMessageVersion" => [MessageVersion, MessageVersionResponse],
+      "getWebVersion" => [WebVersion, WebVersionResponse],
+      "sendEmail" => [SendResult, SendResponse],
+      "sendSms" => [SmsReceipt, ObjectResponse],
+      "sendTestEmail" => [MessageNotice, MessageNoticeResponse],
+      "updateEmailMessage" => [MessageCreated, MessageCreatedResponse],
+      "updateOptInEmail" => [Record, ObjectResponse],
+      "getSenderDomainList" => [SenderDomainGroup, ObjectResponse],
+      "getCampaignCommonStats" => [CampaignStats, CampaignStatsResponse],
+      "async/getCampaignDeliveryStats" => [TaskResult, TaskResultResponse],
+      "getCampaignStatus" => [Status, StatusResponse],
+      "getMessages" => [Message, MessageResponse],
+      "getVisitedLinks" => [Record, ObjectResponse],
+      "listMessages" => [Message, MessageResponse],
+      "getCampaigns" => [Campaign, CampaignResponse],
+      "getMessage" => [Message, MessageResponse],
+      "async/getTaskResult" => [TaskResult, TaskResultResponse],
+      "createEmailTemplate" => [IdentifierRecord, IdentifierRecordResponse],
+      "deleteTemplate" => [Record, ObjectResponse],
+      "getTemplate" => [Template, TemplateResponse],
+      "getTemplates" => [Template, TemplateResponse],
+      "listTemplates" => [Template, TemplateResponse],
+      "updateEmailTemplate" => [IdentifierRecord, IdentifierRecordResponse],
+      "createField" => [IdentifierRecord, IdentifierRecordResponse],
+      "deleteField" => [Record, ObjectResponse],
+      "deleteTag" => [Record, ObjectResponse],
+      "getFields" => [Field, FieldResponse],
+      "getTags" => [Tag, TagResponse],
+      "updateField" => [OptionalIdentifier, OptionalIdentifierResponse],
+      "getContactFieldValues" => [ContactFields, ContactFieldsResponse],
+      "createSubscriberNote" => [IdentifierRecord, IdentifierRecordResponse],
+      "updateSubscriberNote" => [IdentifierRecord, IdentifierRecordResponse],
+      "deleteSubscriberNote" => [Record, ObjectResponse],
+      "getSubscriberNote" => [Note, NoteResponse],
+      "getSubscriberNotes" => [Note, NoteResponse],
+      "listHooks" => [Hook, ObjectResponse]
+    }
+    MODELS = models.freeze
+    COLLECTION_OPERATIONS = %w[getLists checkEmail sendSms getSenderDomainList getMessages listMessages
+                               getCampaigns getVisitedLinks getTemplates listTemplates getFields getTags
+                               getSubscriberNotes listHooks].freeze
+    EMPTY_OPERATIONS = %w[deleteList exclude updateList unsubscribe cancelCampaign deleteMessage
+                          sendTestEmail updateField updateOptInEmail deleteTemplate deleteField
+                          deleteTag deleteSubscriberNote].freeze
+  end
+end

data/lib/unisender/results.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Operation-specific decoding leaves the low-level request path unchanged.
+  module Results
+    def self.build(method, response)
+      return boolean(response) if method == "isContactInLists"
+
+      value = normalize(method, response.result)
+      validate_container(method, value)
+      model, wrapper = MODELS.fetch(method) { [Record, ObjectResponse] }
+      wrap(value, model, wrapper, response)
+    end
+
+    def self.boolean(response)
+      shape_error("Boolean", response.result, "result") unless [true, false].include?(response.result)
+
+      response
+    end
+
+    def self.validate_container(method, value)
+      collection = COLLECTION_OPERATIONS.include?(method)
+      return if collection == value.is_a?(Array)
+
+      shape_error(collection ? "Array" : "Hash", value, "result")
+    end
+
+    def self.normalize(method, value)
+      return normalize_send(method, value) if %w[sendSms sendEmail].include?(method)
+      return single_message(value) if method == "getMessage"
+      return rows(value) if method == "getVisitedLinks"
+      return {} if EMPTY_OPERATIONS.include?(method) && value == []
+
+      value
+    end
+
+    def self.normalize_send(method, value)
+      return value.is_a?(Hash) ? [value] : value if method == "sendSms"
+
+      value.is_a?(Array) ? { "recipients" => value } : value
+    end
+
+    def self.single_message(value)
+      raise NotFoundError, "Message not found" if value.is_a?(Array) && value.empty?
+
+      shape_error("Array with one message", value, "result") unless value.is_a?(Array) && value.size == 1
+
+      value.first
+    end
+
+    def self.wrap(value, model, wrapper, response)
+      if value.is_a?(Array)
+        records = value.each_with_index.map { |item, index| object(model, item, "result[#{index}]") }.freeze
+        CollectionResponse.new(data: response.data, status: response.http_status, headers: response.headers,
+                               result: records)
+      else
+        wrapper.new(data: response.data, status: response.http_status, headers: response.headers,
+                    result: object(model, value))
+      end
+    end
+
+    def self.object(model, value, path = "result")
+      unless value.is_a?(Hash)
+        raise InvalidResponseError.new("Expected result object", expected_type: "Hash",
+                                                                 actual_type: Diagnostics.type_name(value))
+      end
+
+      model.new(value)
+    rescue InvalidResponseError => e
+      raise e.prepend_path(path), cause: nil
+    end
+
+    def self.rows(value)
+      shape_error("Hash", value, "result") unless value.is_a?(Hash)
+      names, data = value.values_at("fields", "data")
+      shape_error("Array", names, "result.fields") unless names.is_a?(Array)
+      shape_error("Array", data, "result.data") unless data.is_a?(Array)
+
+      fields = field_names(names)
+      data.each_with_index.map { |row, index| row_object(fields, row, index) }
+    end
+
+    def self.row_object(fields, row, index)
+      unless row.is_a?(Array) && row.size == fields.size
+        shape_error("Array with #{fields.size} cells", row, "result.data[#{index}]")
+      end
+
+      fields.zip(row).to_h
+    end
+
+    def self.field_names(value)
+      value.each_with_index do |name, index|
+        shape_error("String", name, "result.fields[#{index}]") unless name.is_a?(String)
+      end
+      shape_error("Unique field names", value, "result.fields") unless value.uniq == value
+
+      value # : Array[String]
+    end
+
+    def self.shape_error(expected, value, path)
+      raise InvalidResponseError.new("Unexpected result shape", path:, expected_type: expected,
+                                                                actual_type: Diagnostics.type_name(value))
+    end
+  end
+end

data/lib/unisender/retry_policy.rb

@@ -9,7 +9,7 @@ module Unisender
       getLists getTotalContactsCount getContactCount isContactInLists getContact checkEmail checkSms
       getActualMessageVersion getWebVersion getSenderDomainList getCampaignCommonStats getCampaignStatus
       getMessages getVisitedLinks listMessages getCampaigns getMessage getTemplate getTemplates listTemplates
-      getFields getTags getContactFieldValues getSubscriberNote getSubscriberNotes async/getTaskResult
+      getFields getTags getContactFieldValues getSubscriberNote getSubscriberNotes async/getTaskResult listHooks
     ].freeze
     TRANSIENT_CODES = %w[retry_later api_call_limit_exceeded_for_api_key api_call_limit_exceeded_for_ip].freeze
 
@@ -23,15 +23,15 @@ module Unisender
       freeze
     end
 
-    def call(operation)
+    def call(operation, execution: nil)
       started = @clock.call
       attempts = 0
       begin
         yield
       rescue Error => e
-        raise unless READ_ONLY.include?(operation) && attempts < @max_retries && transient?(e)
+        raise unless READ_ONLY.include?(operation) && attempts < @max_retries && e.transient?
 
-        raise unless wait?(e, attempts, started + @max_elapsed)
+        raise unless wait?(e, attempts, started + @max_elapsed, execution, operation)
 
         attempts += 1
         retry
@@ -49,22 +49,16 @@ module Unisender
       raise ArgumentError, "max_elapsed must be positive and finite"
     end
 
-    def wait?(error, attempts, deadline)
+    def wait?(error, attempts, deadline, execution, operation)
       delay = [(2.0**attempts) + @random.call, retry_after(error)].max
       return false if delay > 30 || @clock.call + delay >= deadline
 
-      @sleeper.call(delay)
-      @clock.call < deadline
-    end
-
-    def transient?(error)
-      case error
-      when APIError then TRANSIENT_CODES.include?(error.code)
-      when HTTPError then [429, 502, 503, 504].include?(error.response.status)
-      when TimeoutError then true
-      when TransportError then error.retryable?
-      else false
+      if execution
+        execution.wait(delay, :retry_wait, operation, @sleeper)
+      else
+        @sleeper.call(delay)
       end
+      @clock.call < deadline
     end
 
     def retry_after(error)

data/lib/unisender/serialization.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Filtering selects root fields only; nested values remain detached copies.
+  module Serialization
+    OPTIONS = %w[only except].freeze
+    def self.payload(value, options = nil)
+      data = Record.copy(value)
+      fields = options_for(options)
+      fields.empty? ? data : filter(data, fields)
+    end
+
+    def self.json(value, options = nil)
+      return payload(value).to_json(options) if options.is_a?(JSON::State)
+
+      payload(value, options).to_json
+    end
+
+    def self.options_for(options)
+      return {} if options.nil?
+      raise ArgumentError, "Serialization options must be a hash" unless options.is_a?(Hash)
+
+      result = {} # : Hash[Symbol, Array[String]]
+      options.each do |key, value|
+        unless OPTIONS.include?(key.to_s) && !result.key?(key.to_s.to_sym)
+          raise ArgumentError, "Unknown or duplicate serialization option"
+        end
+
+        result[key.to_s.to_sym] = field_names(value)
+      end
+      result
+    end
+
+    def self.field_names(value)
+      names = value.is_a?(Array) ? value : [value]
+      unless names.all? { |name| name.is_a?(String) || name.is_a?(Symbol) }
+        raise ArgumentError, "Serialization field names must be strings or symbols"
+      end
+
+      names.map(&:to_s)
+    end
+
+    def self.filter(data, fields)
+      case data
+      when Array then data.map { |item| filter(item, fields) }
+      when Hash
+        only = fields[:only]
+        result = only ? data.slice(*only) : data
+        result.except(*fields.fetch(:except, []))
+      else raise ArgumentError, "Serialization filters require object results"
+      end
+    end
+  end
+end

data/lib/unisender/statistic_records.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Documented campaign stats values.
+  class CampaignStats < Record
+    COUNTERS = %w[total sent delivered read_unique read_all clicked_unique clicked_all unsubscribed spam].freeze
+    def total
+      integer("total")
+    end
+
+    def sent
+      integer("sent")
+    end
+
+    def delivered
+      integer("delivered")
+    end
+
+    def read_unique
+      integer("read_unique")
+    end
+
+    def read_all
+      integer("read_all")
+    end
+
+    def clicked_unique
+      integer("clicked_unique")
+    end
+
+    def clicked_all
+      integer("clicked_all")
+    end
+
+    def unsubscribed
+      integer("unsubscribed")
+    end
+
+    def spam
+      integer("spam")
+    end
+
+    protected
+
+    def normalize
+      COUNTERS.each { |name| @values[name] = integer(name) if @values.key?(name) }
+    end
+  end
+
+  # Transport metadata and CampaignStats readers.
+  class CampaignStatsResponse < ObjectResponse
+    def total
+      result.total
+    end
+
+    def sent
+      result.sent
+    end
+
+    def delivered
+      result.delivered
+    end
+
+    def read_unique
+      result.read_unique
+    end
+
+    def read_all
+      result.read_all
+    end
+
+    def clicked_unique
+      result.clicked_unique
+    end
+
+    def clicked_all
+      result.clicked_all
+    end
+
+    def unsubscribed
+      result.unsubscribed
+    end
+
+    def spam
+      result.spam
+    end
+  end
+
+  # Documented sms receipt values.
+  class SmsReceipt < Record
+    def sms_id
+      identifier!("sms_id")
+    end
+
+    def price
+      number("price")
+    end
+
+    def currency
+      text("currency")
+    end
+
+    protected
+
+    def normalize
+      @values["sms_id"] = sms_id
+      @values["price"] = price if @values.key?("price")
+      @values["currency"] = currency if @values.key?("currency")
+    end
+  end
+
+  # Documented email delivery values.
+  class EmailDelivery < Record
+    def id
+      self["id"].nil? ? nil : identifier!("id")
+    end
+
+    def status
+      text("status")
+    end
+
+    protected
+
+    def normalize
+      @values["id"] = id if @values.key?("id")
+      @values["status"] = status if @values.key?("status")
+    end
+  end
+end

data/lib/unisender/task_response.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Unisender
+  # A task handle polls only when the caller requests it.
+  class TaskResponse < TaskResultResponse
+    attr_reader :task_uuid
+
+    def initialize(response, client:, task_uuid:)
+      @client = client
+      @task_uuid = task_uuid.dup.freeze
+      super(data: response.data, status: response.http_status, headers: response.headers, result: response.result)
+    end
+
+    def wait(interval: 1, timeout: 60, clock: nil, sleeper: nil, &)
+      if completed? || failed?
+        yield self if block_given?
+        raise TaskFailedError.new(self).with_task(task_uuid:, last_response: self) if failed?
+
+        return self
+      end
+
+      @client.wait_for_task(task_uuid:, interval:, timeout:, clock:, sleeper:, &)
+    end
+
+    def completed?
+      status == "completed"
+    end
+
+    def failed?
+      status == "failed"
+    end
+
+    def pending?
+      TaskWaiter::PENDING.include?(status)
+    end
+
+    def download_to(io, max_bytes:, downloader: Downloader.new)
+      @client.check_execution!
+      raise TaskError, self unless status == "completed"
+
+      url = file_to_download
+      raise InvalidResponseError, "Missing task download URL" unless url
+
+      download_file(url, io, max_bytes, downloader)
+    end
+
+    private
+
+    def download_file(url, io, max_bytes, downloader)
+      case downloader
+      when Downloader
+        # rubocop:disable-next Style/ClassEqualityComparison -- Preserve custom subclass types in Steep's fallback.
+        if downloader.class == Downloader
+          return downloader.download(url, io, max_bytes:, execution: @client.execution_context)
+        end
+      end
+      downloader.download(url, io, max_bytes:)
+    end
+  end
+
+  # A task reached the failed terminal state.
+  class TaskFailedError < TaskError
+    def category
+      :task_failed
+    end
+  end
+
+  # A task returned a state not documented by the protocol.
+  class UnknownTaskStateError < TaskError
+    def category
+      :unknown_task_state
+    end
+  end
+
+  # A polling deadline retains the last known task state.
+  class TaskTimeoutError < TimeoutError
+    attr_reader :response, :task_uuid
+
+    def initialize(response)
+      @response = response
+      @task_uuid = response.task_uuid
+      super("Timed out waiting for the UniSender task")
+    end
+  end
+end

data/lib/unisender/task_waiter.rb

@@ -5,24 +5,38 @@ module Unisender
   class TaskWaiter
     PENDING = %w[new processing].freeze
 
-    def initialize(client, clock:, sleeper:)
+    def initialize(client, clock:, sleeper:, progress: nil)
       @client = client
       @clock = clock
       @sleeper = sleeper
+      @progress = progress
     end
 
     def call(task_uuid, interval, timeout)
-      validate!(interval, timeout)
-      deadline = @clock.call + timeout
+      poll(task_uuid, interval, deadline_for(interval, timeout))
+    end
+
+    private
+
+    def poll(task_uuid, interval, deadline)
+      # @type var last_response: TaskResponse?
+      last_response = nil
       loop do
         response = @client.get_task_result(task_uuid:)
+        last_response = response
+        @progress&.call(response)
         return response if complete?(response)
 
-        wait(interval, deadline)
+        wait(interval, deadline, response)
       end
+    rescue Error => e
+      raise e.with_task(task_uuid:, last_response:), cause: nil
     end
 
-    private
+    def deadline_for(interval, timeout)
+      validate!(interval, timeout)
+      @clock.call + timeout
+    end
 
     def validate!(interval, timeout)
       [interval, timeout].each do |value|
@@ -34,19 +48,19 @@ module Unisender
 
     def complete?(response)
       result = response.result
-      raise TaskError, response unless result.is_a?(Hash)
       return true if result["status"] == "completed"
-      raise TaskError, response unless PENDING.include?(result["status"])
+      raise TaskFailedError, response if result["status"] == "failed"
+      raise UnknownTaskStateError, response unless PENDING.include?(result["status"])
 
       false
     end
 
-    def wait(interval, deadline)
+    def wait(interval, deadline, response)
       remaining = deadline - @clock.call
-      raise TimeoutError, "Timed out waiting for the UniSender task" unless remaining.positive?
+      raise TaskTimeoutError, response unless remaining.positive?
 
-      @sleeper.call([interval, remaining].min)
-      raise TimeoutError, "Timed out waiting for the UniSender task" if @clock.call >= deadline
+      @client.execution_wait([interval, remaining].min, :poll_wait, "async/getTaskResult", @sleeper)
+      raise TaskTimeoutError, response if @clock.call >= deadline
     end
   end
 end

data/lib/unisender/testing/assertions.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Unisender
+  module Testing
+    # Compare expected subsets without including payload values in failure messages.
+    module Assertions
+      def self.check(request, form, json)
+        subset!(request.form, form, "") unless form.nil?
+        subset!(request.json, json, "") unless json.nil?
+      rescue JSON::ParserError
+        raise "Expected JSON request body", cause: nil
+      end
+
+      def self.validate(form, json)
+        raise ArgumentError, "Choose expected_form or expected_json" unless form.nil? || json.nil?
+        return unless form&.key?("api_key")
+
+        raise ArgumentError, "Credentials cannot be request expectations"
+      end
+
+      def self.subset!(actual, expected, path)
+        case expected
+        when Hash then hash!(actual, expected, path)
+        when Array then array!(actual, expected, path)
+        else mismatch!(path) unless actual == expected
+        end
+      end
+
+      def self.hash!(actual, expected, path)
+        mismatch!(path) unless actual.is_a?(Hash)
+        expected.each do |key, value|
+          child = path.empty? ? key : "#{path}.#{key}"
+          mismatch!(child) unless actual.key?(key)
+          subset!(actual[key], value, child)
+        end
+      end
+
+      def self.array!(actual, expected, path)
+        mismatch!(path) unless actual.is_a?(Array) && actual.size >= expected.size
+        expected.each_with_index { |value, index| subset!(actual[index], value, "#{path}[#{index}]") }
+      end
+
+      def self.mismatch!(path)
+        raise "Unexpected request value at #{Diagnostics.input_path(path)}"
+      end
+    end
+  end
+end

data/lib/unisender/testing/fixtures.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Unisender
+  module Testing
+    # Wire-shaped values for common application tests, without a response envelope.
+    module Fixtures
+      def self.list(id:, title:)
+        { "id" => id, "title" => title }
+      end
+
+      def self.import_result(total:, invalid: 0, log: [])
+        { "total" => total, "invalid" => invalid, "log" => log }
+      end
+
+      def self.task(status:, task_uuid:, file_to_download: nil)
+        { "status" => status, "task_uuid" => task_uuid, "file_to_download" => file_to_download }.compact
+      end
+
+      def self.recipient(index:, email:, id: nil, errors: [])
+        { "index" => index, "email" => email, "id" => id, "errors" => errors }.compact
+      end
+    end
+  end
+end