unisender-ruby 0.1.0 → 0.2.0

data/lib/unisender/testing.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../unisender"
+require_relative "testing/assertions"
+require_relative "testing/fixtures"
+
+module Unisender
+  # Optional deterministic transport support for application tests.
+  module Testing
+    Request = Data.define(:uri, :headers, :body)
+    Reply = Data.define(:operation, :response, :expected_form, :expected_json)
+
+    # Explicit body access is private data; inspection and form access redact credentials.
+    class Request
+      def operation
+        uri.host == "event.unisender.com" ? "track_events" : uri.path.to_s.split("/api/", 2).last.to_s
+      end
+
+      def form
+        URI.decode_www_form(body).to_h.except("api_key")
+      end
+
+      def json
+        JSON.parse(body) # : json
+      end
+
+      def inspect
+        "#<Unisender::Testing::Request>"
+      end
+
+      alias to_s inspect
+    end
+
+    # Queued responses never open a socket.
+    class Transport
+      def initialize
+        @replies = []
+        @requests = []
+      end
+
+      # rubocop:disable-next Metrics/ParameterLists -- Expectations belong to their queued response.
+      def enqueue(data:, http_status: 200, headers: {}, operation: nil, expected_form: nil, expected_json: nil)
+        reply = HTTPResponse.new(status: http_status, headers:, body: JSON.generate(data))
+        enqueue_response(reply, operation:, expected_form:, expected_json:)
+      end
+
+      def enqueue_response(response, operation: nil, expected_form: nil, expected_json: nil)
+        Assertions.validate(expected_form, expected_json)
+        @replies << Reply.new(operation:, response:, expected_form:, expected_json:)
+        self
+      end
+
+      def requests
+        @requests.dup.freeze
+      end
+
+      def verify!
+        raise "#{@replies.size} queued response(s) were not consumed" unless @replies.empty?
+
+        self
+      end
+
+      def post(uri, headers:, body:)
+        request = Request.new(uri: uri.dup.freeze, headers: headers.dup.freeze, body: body.dup.freeze)
+        @requests << request
+        response = next_response(request)
+        raise response if response.is_a?(StandardError)
+
+        response
+      end
+
+      def inspect
+        "#<Unisender::Testing::Transport>"
+      end
+
+      private
+
+      def next_response(request)
+        reply = @replies.shift or raise "Unexpected request: no queued response"
+        if reply.operation && reply.operation != request.operation
+          expected = Error.safe_operation(reply.operation) || "request"
+          actual = Error.safe_operation(request.operation) || "request"
+          raise "Unexpected request: expected #{expected}, received #{actual}"
+        end
+
+        Assertions.check(request, reply.expected_form, reply.expected_json)
+        reply.response
+      end
+    end
+  end
+end

data/lib/unisender/transport.rb

@@ -16,11 +16,10 @@ module Unisender
       @read_timeout = read_timeout
       @write_timeout = write_timeout
       @http_factory = http_factory || ->(uri) { Net::HTTP.new(uri.hostname.to_s, uri.port) }
-      freeze
     end
 
-    def post(uri, headers:, body:)
-      exchange(uri, headers:, body:)
+    def post(uri, headers:, body:, execution: nil)
+      exchange(uri, headers:, body:, execution:)
     rescue Timeout::Error
       raise TimeoutError, "UniSender request timed out", cause: nil
     rescue OpenSSL::SSL::SSLError
@@ -31,23 +30,32 @@ module Unisender
 
     private
 
-    def exchange(uri, headers:, body:)
+    def exchange(uri, headers:, body:, execution:)
       request = Net::HTTP::Post.new(uri, headers)
       request.body = body
-      response = configured_http(uri).request(request)
+      response = perform(uri, request, execution:)
       headers = response.to_hash.transform_values { |items| items.join(", ") }
       HTTPResponse.new(status: response.code.to_i, headers:, body: response.body.to_s)
     end
 
-    def configured_http(uri)
+    def perform(uri, request, execution:)
+      configured_http(uri, execution:).request(request)
+    end
+
+    def configured_http(uri, execution: nil)
       http = @http_factory.call(uri)
       http.use_ssl = true
       http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-      http.open_timeout = @open_timeout
-      http.read_timeout = @read_timeout
-      http.write_timeout = @write_timeout
+      configure_timeouts(http, execution)
       http.max_retries = 0
       http
     end
+
+    def configure_timeouts(http, execution)
+      remaining = execution&.remaining
+      http.open_timeout = remaining ? [@open_timeout, remaining].min : @open_timeout
+      http.read_timeout = remaining ? [@read_timeout, remaining].min : @read_timeout
+      http.write_timeout = remaining ? [@write_timeout, remaining].min : @write_timeout
+    end
   end
 end

data/lib/unisender/validation.rb

@@ -19,20 +19,19 @@ module Unisender
     def self.campaign!(params)
       return unless params[:contacts] && params[:contacts_url]
 
-      raise ArgumentError,
-            "contacts and contacts_url are mutually exclusive"
+      raise ValidationError.new(field: "contacts", code: :conflicting_input)
     end
 
     def self.template!(params)
       return unless params[:template_id].nil? && params[:system_template_id].nil?
 
-      raise ArgumentError, "Provide template_id or system_template_id"
+      raise ValidationError.new(field: "template_id", code: :required_alternative)
     end
 
     def self.import!(params)
       fields = params[:field_names]
       unless fields.is_a?(Array) && fields.all?(String) && fields.include?("email") && fields.uniq == fields
-        raise ArgumentError, "field_names must contain unique column names including email"
+        raise ValidationError.new(field: "field_names", code: :invalid_columns)
       end
 
       rows!(params[:data], fields.size)
@@ -42,14 +41,14 @@ module Unisender
       unless rows.is_a?(Array) && (1..500).cover?(rows.size) && rows.all? do |row|
         row.is_a?(Array) && row.size == width
       end
-        raise ArgumentError, "data must contain 1 to 500 rows matching field_names"
+        raise ValidationError.new(field: "data", code: :invalid_rows)
       end
     end
 
     def self.required!(params, names)
       names.each do |name|
         value = params[name.to_sym]
-        raise ArgumentError, "Missing required parameter: #{name}" if missing?(value)
+        raise ValidationError.new(field: name, code: :required) if missing?(value)
       end
     end
 
@@ -61,9 +60,12 @@ module Unisender
       end
     end
 
-    def self.comma_list(value)
-      unless value.all? { |item| item.is_a?(String) || item.is_a?(Integer) }
-        raise ArgumentError, "Comma-separated lists require strings or integers"
+    def self.comma_list(value, field: "parameters")
+      value.each_with_index do |item, index|
+        next if item.is_a?(String) || item.is_a?(Integer)
+
+        raise ValidationError.new(field: "#{field}[#{index}]", code: :invalid_list,
+                                  expected_type: "String or Integer", actual_type: Diagnostics.type_name(item))
       end
 
       value.join(",")

data/lib/unisender/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Unisender
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/unisender/webhooks/tokens.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Unisender
+  module Webhooks
+    # Scan strings and structural tokens once, preserving original byte offsets.
+    class Tokens
+      def initialize(text)
+        @text = text
+      end
+
+      def each
+        index = 0
+        while index < @text.bytesize
+          token, finish = read(index)
+          yield token, index, finish if token.start_with?('"') || "{}[],".include?(token)
+          index = finish
+        end
+      end
+
+      private
+
+      def read(index)
+        finish = @text.getbyte(index) == 34 ? string_end(index + 1) : index + 1
+        [@text.byteslice(index...finish).to_s, finish]
+      end
+
+      def string_end(index)
+        while index < @text.bytesize
+          byte = @text.getbyte(index)
+          return index + 1 if byte == 34
+
+          index += byte == 92 ? 2 : 1
+        end
+        raise WebhookError, :malformed_payload
+      end
+    end
+  end
+end

data/lib/unisender/webhooks.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require_relative "../unisender"
+require "digest"
+require "zlib"
+require "stringio"
+require_relative "webhooks/tokens"
+
+module Unisender
+  # Rejected inbound data never appears in exception messages.
+  class WebhookError < Error
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super("Invalid webhook: #{reason}")
+    end
+
+    def category
+      :invalid_webhook
+    end
+  end
+
+  # A notification event keeps its schema-specific fields in event_data.
+  class WebhookEvent < Record
+    def event_name
+      text!("event_name")
+    end
+
+    def event_time
+      text!("event_time")
+    end
+
+    def event_data
+      value = self["event_data"]
+      raise WebhookError, :invalid_event unless value.is_a?(Record)
+
+      value
+    end
+
+    protected
+
+    def normalize
+      event_name
+      event_time
+      event_data
+    end
+  end
+
+  # Events grouped by the account login from the notification.
+  class WebhookUser < Record
+    def login
+      text!("login")
+    end
+
+    def events
+      raise WebhookError, :conflicting_events if key?("events") && key?("Events")
+
+      values = self[key?("events") ? "events" : "Events"]
+      raise WebhookError, :unsupported_shape unless values.is_a?(Array)
+
+      Outcomes.records(values, "events").map { |event| WebhookEvent.new(event.to_h) }
+    end
+
+    protected
+
+    def normalize
+      login
+      raise WebhookError, :unsupported_shape unless key?("events") || key?("Events")
+
+      events
+    end
+  end
+
+  # Authenticated notification payload with typed user and event readers.
+  class WebhookNotification < Record
+    def users
+      Outcomes.records(self["events_by_user"], "events_by_user").map { |user| WebhookUser.new(user.to_h) }
+    end
+
+    def events
+      users.flat_map(&:events)
+    end
+
+    protected
+
+    def normalize
+      raise WebhookError, :unsupported_shape unless self["events_by_user"].is_a?(Array)
+
+      users
+    end
+  end
+
+  # The documented signature covers original decompressed JSON bytes.
+  module Webhooks
+    # The token walk rejects duplicate keys even on older JSON parsers.
+    class ObjectKeys
+      attr_reader :key
+
+      def initialize
+        @seen = {}
+        @key = nil
+      end
+
+      def register(token)
+        return if @key
+
+        key = JSON.parse(token) # : String
+        raise WebhookError, :duplicate_key if @seen.key?(key)
+
+        @seen[key] = true
+        @key = key
+      end
+
+      def next_key
+        @key = nil
+      end
+    end
+
+    # rubocop:disable-next Metrics/ParameterLists -- Independent receiver limits are explicit.
+    def self.verify(body:, api_key:, content_encoding: nil, max_bytes: 1_048_576,
+                    max_decompressed_bytes: 4_194_304, max_events: 10_000)
+      validate_limits(max_bytes, max_decompressed_bytes, max_events)
+      raise WebhookError, :too_large if body.bytesize > max_bytes
+
+      bytes = decompress(body, content_encoding, max_decompressed_bytes)
+      data = decode(bytes)
+      authenticate(bytes, data, api_key)
+      notification = WebhookNotification.new(data)
+      raise WebhookError, :too_many_events if notification.events.size > max_events
+
+      notification
+    rescue JSON::ParserError, EncodingError, InvalidResponseError, TypeError, ArgumentError
+      raise WebhookError, :malformed_payload, cause: nil
+    end
+
+    def self.decode(bytes)
+      data = JSON.parse(bytes, max_nesting: 64) # : json
+      raise WebhookError, :unsupported_shape unless data.is_a?(Hash)
+
+      data
+    end
+
+    def self.validate_limits(*limits)
+      return if limits.all? { |value| value.is_a?(Integer) && value.positive? }
+
+      raise WebhookError, :invalid_limits
+    end
+
+    def self.decompress(body, encoding, limit)
+      case encoding
+      when nil, "", "identity" then bounded(body, limit)
+      when "gzip" then inflate(body, limit)
+      else raise WebhookError, :unsupported_encoding
+      end
+    rescue Zlib::Error, EOFError
+      raise WebhookError, :invalid_gzip, cause: nil
+    end
+
+    def self.inflate(body, limit)
+      gzip = Zlib::GzipReader.new(StringIO.new(body))
+      begin
+        result = bounded(gzip.read(limit + 1).to_s, limit)
+        raise WebhookError, :trailing_data unless gzip.unused.to_s.empty?
+
+        result
+      ensure
+        gzip.close
+      end
+    end
+
+    def self.bounded(body, limit)
+      raise WebhookError, :too_large if body.bytesize > limit
+
+      text = body.dup.force_encoding(Encoding::UTF_8)
+      raise WebhookError, :invalid_encoding unless text.valid_encoding?
+
+      text
+    end
+
+    def self.authenticate(bytes, data, api_key)
+      auth = auth_value(data)
+      start, finish = auth_span(bytes)
+      signed = bytes.byteslice(0...start).to_s + JSON.generate(api_key) + bytes.byteslice(finish..).to_s
+      # UniSender requires MD5; the accepted protocol exception is documented in docs/webhooks.md.
+      expected = Digest::MD5.hexdigest(signed)
+      raise WebhookError, :invalid_auth unless secure_equal?(auth, expected)
+    end
+
+    def self.auth_value(data)
+      auth = data["auth"]
+      raise WebhookError, :invalid_auth unless auth.is_a?(String) && auth.match?(/\A[0-9a-f]{32}\z/)
+
+      auth
+    end
+
+    def self.secure_equal?(actual, expected)
+      actual.bytes.zip(expected.bytes).reduce(0) { |memo, (a, b)| memo | (a ^ b.to_i) }.zero?
+    end
+
+    # rubocop:disable-next Metrics/MethodLength, Metrics/CyclomaticComplexity -- Preserve JSON spans.
+    def self.auth_span(bytes)
+      # @type var stack: Array[ObjectKeys?]
+      stack = []
+      # @type var span: [Integer, Integer]?
+      span = nil
+      Tokens.new(bytes).each do |token, start, finish|
+        case token
+        when "{" then stack << ObjectKeys.new
+        when "[" then stack << nil
+        when "}", "]" then stack.pop
+        when "," then stack.last&.next_key
+        else
+          span = register_string(stack, token, start, finish) || span
+        end
+      end
+      span || raise(WebhookError, :invalid_auth)
+    end
+
+    def self.register_string(stack, token, start, finish)
+      frame = stack.last
+      return unless frame
+
+      # @type var span: [Integer, Integer]?
+      span = [start, finish] if stack.size == 1 && frame.key == "auth"
+      frame.register(token)
+      span
+    end
+  end
+end

data/lib/unisender.rb

@@ -4,19 +4,60 @@ require_relative "unisender/version"
 require "uri"
 require_relative "unisender/response"
 require_relative "unisender/errors"
+require_relative "unisender/record"
+require_relative "unisender/serialization"
+require_relative "unisender/records"
+require_relative "unisender/hooks"
+require_relative "unisender/outcomes"
+require_relative "unisender/contact_records"
+require_relative "unisender/statistic_records"
+require_relative "unisender/task_response"
+require_relative "unisender/result_registry"
+require_relative "unisender/results"
 require_relative "unisender/protocol"
 require_relative "unisender/form"
 require_relative "unisender/transport"
+require_relative "unisender/persistent_transport"
+require_relative "unisender/rate_limiter"
+require_relative "unisender/download_target"
+require_relative "unisender/download_transfer"
+require_relative "unisender/downloader"
 require_relative "unisender/validation"
+require_relative "unisender/attachment"
+require_relative "unisender/inputs"
+require_relative "unisender/named_inputs"
+require_relative "unisender/mail_inputs"
+require_relative "unisender/input_types"
+require_relative "unisender/operation_contracts"
+require_relative "unisender/diagnostic_urls"
+require_relative "unisender/diagnostics"
+require_relative "unisender/import_cells"
+require_relative "unisender/record_rows"
 require_relative "unisender/event_payload"
 require_relative "unisender/retry_policy"
+require_relative "unisender/error_diagnostics"
+require_relative "unisender/observation"
+require_relative "unisender/acceptance"
+require_relative "unisender/client_state"
+require_relative "unisender/configuration"
 require_relative "unisender/client"
+require_relative "unisender/execution_context"
+require_relative "unisender/client_execution"
+require_relative "unisender/request_execution"
+require_relative "unisender/client_configuration"
+require_relative "unisender/client_validation"
 require_relative "unisender/events"
 require_relative "unisender/paginated_operations"
 require_relative "unisender/pagination"
+require_relative "unisender/iteration"
+require_relative "unisender/page_response"
 require_relative "unisender/batches"
+require_relative "unisender/event_batches"
+require_relative "unisender/batch_report"
+require_relative "unisender/batch_summary"
 require_relative "unisender/task_waiter"
 require_relative "unisender/helpers"
+require_relative "unisender/iterators"
 require_relative "unisender/operations/contacts_1"
 require_relative "unisender/operations/contacts_2"
 require_relative "unisender/operations/inputs_1"
@@ -27,3 +68,4 @@ require_relative "unisender/operations/notes_1"
 require_relative "unisender/operations/statistics_1"
 require_relative "unisender/operations/statistics_2"
 require_relative "unisender/operations/templates_1"
+require_relative "unisender/campaign_workflow"

data/sig/acceptance.rbs

@@ -0,0 +1,30 @@
+module Unisender
+  class AcceptanceEvent < Data
+    attr_reader operation: String
+    attr_reader outcome: Symbol
+    attr_reader input_count: Integer
+    attr_reader accepted_count: Integer?
+    attr_reader rejected_count: Integer?
+    attr_reader unknown_count: Integer?
+    attr_reader row_warning_count: Integer?
+    attr_reader request_id: String?
+    def self.new: (operation: String, outcome: Symbol, input_count: Integer, accepted_count: Integer?, rejected_count: Integer?, unknown_count: Integer?, row_warning_count: Integer?, request_id: String?) -> AcceptanceEvent
+  end
+  module Acceptance
+    def self.input_count: (String, params) -> Integer?
+    def self.event: (String, Integer, Response?, StandardError?) -> AcceptanceEvent
+    def self.warning_count: (Response?) -> Integer?
+    def self.counts: (Integer, Response?, StandardError?) -> [Integer?, Integer?, Integer?]
+    def self.bounded_counts: (Integer, [Integer?, Integer?, Integer?]) -> [Integer?, Integer?, Integer?]
+    def self.send_counts: (Integer, SendResponse) -> [Integer, Integer, Integer]
+    def self.import_counts: (Integer, ImportResponse) -> [Integer?, Integer, Integer?]
+    def self.state: (Response?, StandardError?, Integer?) -> Symbol
+    def self.failure_state: (StandardError) -> Symbol
+    def self.result_state: (OutcomeResponse) -> Symbol
+    def self.emit: (^(AcceptanceEvent) -> void, AcceptanceEvent) -> void
+  end
+  class Client
+    private
+    def observe_acceptance: (String, Integer?, Response?, StandardError?) -> void
+  end
+end

data/sig/attachment.rbs

@@ -0,0 +1,15 @@
+module Unisender
+  interface _Readable
+    def read: (?Integer) -> String?
+  end
+  class Attachment
+    attr_reader filename: String
+    attr_reader bytes: String
+    def initialize: (filename: String, bytes: String) -> void
+    def self.from_path: (String, ?filename: String, ?max_bytes: Integer?) -> Attachment
+    def self.from_io: (_Readable, filename: String, ?max_bytes: Integer?) -> Attachment
+    def inspect: () -> String
+    private
+    def self.read_size: (Integer?) -> Integer?
+  end
+end

data/sig/batch_summary.rbs

@@ -0,0 +1,38 @@
+module Unisender
+  class BatchProgress < Data
+    attr_reader completed_batches: Integer
+    attr_reader completed_items: Integer
+    attr_reader next_index: Integer
+    attr_reader invalid: Integer
+    attr_reader warning_count: Integer
+    attr_reader response: Response?
+    def self.new: (completed_batches: Integer, completed_items: Integer, next_index: Integer, invalid: Integer, warning_count: Integer, response: Response?) -> BatchProgress
+  end
+  class BatchSummary
+    @failure: BatchReport
+    attr_reader completed_batches: Integer
+    attr_reader completed_items: Integer
+    attr_reader invalid: Integer
+    attr_reader warning_count: Integer
+    def initialize: (BatchProgress, ?error: StandardError?, ?failed_range: Range[Integer]?) -> void
+    def complete?: () -> bool
+    def partial?: () -> bool
+    def uncertain?: () -> bool
+    def failures: () -> Array[Failure]
+    def row_warnings: () -> Array[Failure]
+  end
+  class BatchAccumulator
+    @retention: Symbol?
+    @offsets: Array[Integer]
+    @completed_batches: Integer
+    @invalid: Integer
+    @warning_count: Integer
+    attr_reader responses: Array[Response]
+    attr_reader completed_items: Integer
+    def initialize: (Symbol?) -> void
+    def add: (Response, Integer) -> void
+    def progress: (?response: Response?) -> BatchProgress
+    def report: (?error: StandardError?, ?failed_range: Range[Integer]?) -> (BatchReport | BatchSummary)
+    def failure: (StandardError, Range[Integer]) -> BatchError
+  end
+end

data/sig/campaign_workflow.rbs

@@ -0,0 +1,20 @@
+module Unisender
+  class CampaignReceipt < Data
+    attr_reader message: MessageCreatedResponse
+    attr_reader campaign: CampaignCreatedResponse
+    def self.new: (message: MessageCreatedResponse, campaign: CampaignCreatedResponse) -> CampaignReceipt
+  end
+  class CampaignWorkflowError < Error
+    attr_reader message_response: MessageCreatedResponse
+    attr_reader error: StandardError
+    def initialize: (MessageCreatedResponse, StandardError) -> void
+  end
+  class Client
+    def send_campaign: (message: Hash[Symbol, parameter], ?campaign: Hash[Symbol, parameter]) -> CampaignReceipt
+    private
+    def campaign_parameters: (Hash[Symbol, parameter], Hash[Symbol, parameter]) -> [params, params]
+    def workflow_keys!: (params, Symbol) -> void
+    def workflow_options!: (params, params) -> void
+    def finish_campaign: (MessageCreatedResponse, params) -> CampaignReceipt
+  end
+end