unisender-ruby 0.1.0 → 0.2.0

data/lib/unisender/batch_summary.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Unisender
+  BatchProgress = Data.define(:completed_batches, :completed_items, :next_index, :invalid, :warning_count, :response)
+
+  # Bounded completed-work metadata; only the failing response is retained.
+  class BatchSummary
+    attr_reader :completed_batches, :completed_items, :invalid, :warning_count
+
+    def initialize(progress, error: nil, failed_range: nil)
+      @completed_batches = progress.completed_batches
+      @completed_items = progress.completed_items
+      @invalid = progress.invalid
+      @warning_count = progress.warning_count
+      @failure = BatchReport.new([], error:, failed_range:)
+      freeze
+    end
+
+    def complete?
+      @failure.complete?
+    end
+
+    def partial?
+      !complete? && (completed_batches.positive? || @failure.partial?)
+    end
+
+    def uncertain?
+      @failure.uncertain?
+    end
+
+    def failures
+      @failure.failures
+    end
+
+    def row_warnings
+      @failure.row_warnings
+    end
+  end
+
+  # Stores source offsets independently from optional upstream counters.
+  class BatchAccumulator
+    attr_reader :responses, :completed_items
+
+    def initialize(retention)
+      raise ValidationError.new(field: "retention", code: :invalid_choice) unless %i[full summary].include?(retention)
+
+      @retention = retention
+      @responses = []
+      @offsets = []
+      @completed_items = 0
+      @completed_batches = 0
+      @invalid = 0
+      @warning_count = 0
+    end
+
+    def add(response, count)
+      if @retention == :full
+        @offsets << @completed_items
+        @responses << response
+      end
+      @completed_items += count
+      @completed_batches += 1
+      return unless response.is_a?(ImportResponse)
+
+      @invalid += response.invalid
+      @warning_count += response.row_warnings.size
+    end
+
+    def progress(response: nil)
+      BatchProgress.new(completed_batches: @completed_batches, completed_items: @completed_items,
+                        next_index: @completed_items, invalid: @invalid, warning_count: @warning_count, response:)
+    end
+
+    def report(error: nil, failed_range: nil)
+      if @retention == :summary
+        BatchSummary.new(progress, error:, failed_range:)
+      else
+        BatchReport.new(@responses, offsets: @offsets, error:, failed_range:)
+      end
+    end
+
+    def failure(error, range)
+      BatchError.new(completed_responses: @responses, failed_range: range, error:,
+                     report: report(error:, failed_range: range))
+    end
+  end
+end

data/lib/unisender/batches.rb

@@ -3,29 +3,58 @@
 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
+    # rubocop:disable-next Metrics/ParameterLists -- Shared explicit batch controls.
+    def self.each(items, size, maximum, accumulator: nil, retention: :full, on_progress: nil, execution: nil, &)
+      validate_size(size, maximum)
+      each_chunks(items.each_slice(size), accumulator:, retention:, on_progress:, execution:, &)
+    end
 
+    # rubocop:disable-next Metrics/MethodLength -- Keep accounting next to the yielding boundary.
+    def self.each_chunks(chunks, accumulator: nil, retention: :full, on_progress: nil, execution: nil, &operation)
       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
+        state = accumulator || BatchAccumulator.new(retention)
+        cursor = chunks.to_enum
+        offset = 0
+        while (batch = next_chunk(cursor, offset, state, execution))
+          response = execute(batch, offset, state, &operation)
+          state.add(response, batch.size)
+          offset += batch.size
+          progress(on_progress, state, offset, response)
           output << response
         end
       end
     end
 
-    def self.execute(batch, offset, completed)
+    def self.validate_size(size, maximum)
+      return if size.is_a?(Integer) && size.positive? && size <= maximum
+
+      raise ValidationError.new(field: "batch_size", code: :invalid_range)
+    end
+
+    def self.next_chunk(chunks, offset, accumulator, execution)
+      execution&.check!
+      chunks.next
+    rescue StopIteration
+      nil
+    rescue StandardError => e
+      position = e.is_a?(ValidationError) ? e.index : nil
+      endpoint = position ? position + 1 : offset
+      raise accumulator.failure(e, offset...endpoint), cause: nil
+    end
+
+    def self.execute(batch, offset, accumulator)
       response = yield batch
-      result = response.result
-      raise PartialFailure, response if result.is_a?(Hash) && result.fetch("invalid", 0).to_s.to_i.positive?
+      raise PartialFailure, response if response.is_a?(OutcomeResponse) && !response.complete?
 
       response
     rescue Error, ArgumentError => e
-      raise BatchError.new(completed_responses: completed, failed_range: offset...(offset + batch.size), error: e),
-            cause: nil
+      raise accumulator.failure(e, offset...(offset + batch.size)), cause: nil
+    end
+
+    def self.progress(callback, accumulator, offset, response)
+      callback&.call(accumulator.progress(response:))
+    rescue StandardError => e
+      raise accumulator.failure(e, offset...offset), cause: nil
     end
   end
 end

data/lib/unisender/campaign_workflow.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Both responses are retained after a completed workflow.
+  CampaignReceipt = Data.define(:message, :campaign)
+
+  # A created message remains available when campaign creation fails.
+  class CampaignWorkflowError < Error
+    attr_reader :message_response, :error
+
+    def initialize(message_response, error)
+      @message_response = message_response
+      @error = error
+      super("Campaign creation failed after message creation")
+    end
+
+    def category
+      error = @error
+      error.is_a?(Error) || error.is_a?(ValidationError) ? error.category : :unexpected
+    end
+
+    def request_id
+      error = @error
+      error.request_id if error.is_a?(Error)
+    end
+  end
+
+  # Validates both steps before creating a message.
+  class Client
+    def send_campaign(message:, campaign: {})
+      message_params, campaign_params = campaign_parameters(message, campaign)
+      created = invoke("createEmailMessage", message_params, required: EMAIL_REQUIRED) # : MessageCreatedResponse
+      finish_campaign(created, campaign_params)
+    end
+
+    private
+
+    def campaign_parameters(message, campaign)
+      workflow_options!(message, campaign)
+
+      defaults = { sender_name: UNSET, sender_email: UNSET, lang: UNSET }
+      message_params = prepare("createEmailMessage", defaults.merge(message), required: EMAIL_REQUIRED,
+                                                                              comma: %w[categories])
+      campaign_params = prepare("createCampaign", campaign.merge(message_id: 0), required: CAMPAIGN_REQUIRED,
+                                                                                 comma: %w[contacts])
+      Form.encode(message_params)
+      Form.encode(campaign_params)
+      [message_params, campaign_params]
+    end
+
+    def workflow_options!(message, campaign)
+      workflow_keys!(message, :create_email_message)
+      workflow_keys!(campaign, :create_campaign)
+      raise ArgumentError, "The workflow supplies message_id" if campaign.key?(:message_id)
+    end
+
+    def workflow_keys!(params, operation)
+      allowed = method(operation).parameters.map(&:last)
+      return if params.keys.all? { |key| allowed.include?(key) }
+
+      raise ArgumentError, "Unknown workflow option"
+    end
+
+    def finish_campaign(created, params)
+      response = invoke("createCampaign", params.merge(message_id: created.message_id),
+                        required: CAMPAIGN_REQUIRED) # : CampaignCreatedResponse
+      CampaignReceipt.new(message: created, campaign: response)
+    rescue Error, ArgumentError => e
+      raise CampaignWorkflowError.new(created, e), cause: nil
+    end
+  end
+end

data/lib/unisender/client.rb

@@ -3,57 +3,89 @@
 module Unisender
   # Synchronous client for the documented UniSender API.
   class Client
+    USER_AGENT = "unisender-ruby/#{VERSION} Ruby/#{RUBY_VERSION}".freeze
     RESERVED_PARAMETERS = %w[api_key format].freeze
+    TASK_METHODS = %w[async/exportContacts async/getCampaignDeliveryStats async/getTaskResult].freeze
+    UNSET = :__unisender_unset__
+    EMAIL_REQUIRED = %w[sender_name sender_email list_id].freeze
+    CAMPAIGN_REQUIRED = %w[message_id].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
+    # @type method initialize: (api_key: String, **config_value) -> void
+    def initialize(api_key:, **)
+      @configuration = Configuration.new(api_key:, **)
+      @api_key = @configuration.api_key
+      @language = @configuration.language
+      @transport = @configuration.transport
+      @retry_policy = @configuration.retry_policy
+      @execution = nil
       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"
+    # @api private
+    # Shared dispatcher for named operations and pagination.
+    # @type method invoke: (String, params, ?required: Array[String], ?comma: Array[String]) -> Response
+    def invoke(method, params, required: [], comma: [])
+      params = prepare(method, params, required:, comma:)
+      perform_request(method, params, named: true)
+    rescue Error, ValidationError => e
+      raise e.with_operation(method), cause: nil
     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: [])
+    def prepare(method, params, required: [], comma: [])
+      params = preparation_defaults(method).merge(params)
+      params = message_defaults(params)
+      OperationContracts.validate!(method, params)
+      params = Inputs.normalize(method, params)
       Validation.required!(params, required)
       Validation.operation!(method, params)
+      comma_parameters(params, comma)
+    rescue ValidationError => e
+      raise e.with_operation(method), cause: nil
+    end
+
+    def preparation_defaults(method)
+      case method
+      when "createEmailMessage", "sendEmail"
+        # @type var values: params
+        values = { sender_name: UNSET, sender_email: UNSET, lang: UNSET }
+        values[:error_checking] = true if method == "sendEmail"
+        values
+      when "setHook" then { event_format: :json_post_gzip, single_event: false, status: :active }
+      else {}
+      end
+    end
+
+    def comma_parameters(params, comma)
       comma.each do |name|
         value = params[name.to_sym]
-        params[name.to_sym] = Validation.comma_list(value) if value.is_a?(Array)
+        params[name.to_sym] = Validation.comma_list(value, field: name) if value.is_a?(Array)
+      end
+      params
+    end
+
+    def message_defaults(params)
+      params.to_h do |key, value|
+        default = @configuration.message_defaults[key.to_s.to_sym] if value == UNSET
+        [key, value == UNSET ? default : value]
       end
-      request(method, params:)
     end
+
+    def bind_task(method, response, params)
+      return response unless TASK_METHODS.include?(method)
+
+      task = response # : TaskResultResponse
+      uuid = params[:task_uuid] || task.task_uuid
+      raise InvalidResponseError, "Missing task UUID" unless uuid.is_a?(String)
+
+      TaskResponse.new(task, client: self, task_uuid: uuid)
+    end
+
+    public :invoke
   end
 end

data/lib/unisender/client_configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Explicit construction, immutable configuration variants, and lifetime.
+  class Client
+    class << self
+      def open(api_key:, **)
+        raise ArgumentError, "Client.open requires a block" unless block_given?
+
+        client = new(api_key:, **)
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      end
+
+      # rubocop:disable-next Metrics/ParameterLists -- Mirrors the constructor options for typed forwarding.
+      def from_env(env: ENV, 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)
+        key = env["UNISENDER_API_KEY"]
+        raise ArgumentError, "UNISENDER_API_KEY is required" unless key
+
+        new(api_key: key, language:, transport:, retry_policy:, open_timeout:, read_timeout:, write_timeout:,
+            max_retries:, max_elapsed:, message_defaults:, instrumentation:, persistent:, rate_limiter:,
+            event_rate_limiter:, acceptance_instrumentation:)
+      end
+    end
+
+    # @type method with: (**config_value) -> Client
+    def with(**options)
+      settings = @configuration.options_for(options)
+      key = settings.delete(:api_key)
+      case key
+      when String
+        client = Client.new(api_key: key, **settings)
+        context = @execution
+        context&.own(client)
+        context ? client.execution_client(context) : client
+      else raise ArgumentError, "api_key must be a string"
+      end
+    end
+
+    def close
+      @configuration.close unless @execution
+    end
+  end
+end

data/lib/unisender/client_execution.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Scoped execution shares the original client's transport and lifetime.
+  class Client
+    def with_execution(timeout: nil, cancellation: nil, instrumentation: nil)
+      context = ExecutionContext.new(timeout:, cancellation:, instrumentation:, parent: @execution)
+      scoped = execution_client(context)
+      begin
+        context.measure(:workflow, "workflow") { yield scoped }
+      ensure
+        context.close
+      end
+    end
+
+    # Shared by helpers so waits observe the same budget as requests.
+    def execution_wait(delay, kind, operation, sleeper)
+      context = @execution
+      if context
+        context.wait(delay, kind, operation, sleeper)
+      else
+        sleeper.call(delay)
+      end
+    end
+
+    def check_execution!
+      @configuration.check_open!
+      @execution&.check!
+    end
+
+    def execution_context
+      @execution
+    end
+
+    protected
+
+    def execution_client(context)
+      client = dup
+      client.instance_variable_set(:@execution, context)
+      client.freeze
+    end
+  end
+end

data/lib/unisender/client_state.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Unisender
+  # The client has completed its resource lifetime.
+  class ClientClosedError < Error
+    def category
+      :client_closed
+    end
+  end
+
+  # Mutable resource lifetime is separate from immutable client options.
+  class ClientState
+    def initialize
+      @closed = false
+      @mutex = Mutex.new
+    end
+
+    def check_open!
+      @mutex.synchronize { raise ClientClosedError, "Client is closed" if @closed }
+    end
+
+    def close
+      @mutex.synchronize do
+        return if @closed
+
+        @closed = true
+        yield
+      end
+    end
+  end
+end

data/lib/unisender/client_validation.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Unisender
+  # The same named preparation is available without crossing the transport seam.
+  class Client
+    def validate!(operation, records: nil, **params)
+      if records
+        raise ArgumentError, "Records require import_contacts" unless operation == :import_contacts
+
+        params = validation_import(params, records)
+      end
+      validation_dispatch(operation, params)
+    end
+
+    private
+
+    def validation_dispatch(operation, params)
+      case operation
+      when :send_campaign then validate_campaign(params)
+      when :track_events then validate_events(params)
+      else validate_named(operation, params)
+      end
+    end
+
+    def validate_named(operation, params)
+      wire = OperationContracts.wire_name(operation)
+      OperationContracts.validate_keys!(wire, params)
+      params = validation_page(operation, params) if PaginatedOperations.supports?(operation)
+      Form.encode(prepare(wire, validation_parameters(wire, params), comma: OperationContracts.comma_fields(wire)))
+      true
+    rescue ValidationError => e
+      raise e.with_operation(wire || operation.to_s), cause: nil
+    end
+
+    def validation_page(operation, params)
+      PaginatedOperations.prepare(operation, params)
+    end
+
+    # rubocop:disable-next Naming/PredicateMethod -- Validation returns true or raises.
+    def validate_campaign(params)
+      raise ValidationError.new(field: "parameters", code: :unknown_keyword) unless (params.keys - %i[message
+                                                                                                      campaign]).empty?
+
+      # @type var empty: params
+      empty = {}
+      message = validation_keywords(params[:message], "message")
+      campaign = validation_keywords(params.fetch(:campaign, empty), "campaign")
+      campaign_parameters(message, campaign)
+      true
+    end
+
+    def validation_keywords(value, field)
+      raise ValidationError.new(field:, code: :invalid_type) unless value.is_a?(Hash)
+
+      value.to_h do |key, item|
+        raise ValidationError.new(field:, code: :unknown_keyword) unless key.is_a?(Symbol)
+
+        [key, item]
+      end
+    end
+
+    def validate_events(params)
+      raise ValidationError.new(field: "events", code: :invalid_type) unless params.keys == [:events]
+
+      events = params.fetch(:events)
+      EventPayload.encode(events)
+      true
+    rescue ValidationError => e
+      raise e.with_operation("track_events"), cause: nil
+    end
+
+    def validation_import(params, records)
+      raise ValidationError.new(field: "records", code: :conflicting_input) if params[:field_names] || params[:data]
+
+      rows = RecordRows.bounded(records)
+      data = rows.to_a
+      params.merge(field_names: rows.field_names, data:)
+    end
+
+    def validation_parameters(wire, params)
+      case wire
+      when "subscribe"
+        params.except(:email).merge(fields: Inputs.contact_fields(params[:fields], params[:email]))
+      when "exclude", "unsubscribe" then ContactInputs.contact_selector(params, wire)
+      when "getContactCount" then validation_count(params)
+      when "setHook"
+        params.merge(events: hook_events(params[:events], params[:max_parallel]))
+      else params
+      end
+    end
+
+    def validation_count(params)
+      filters = ContactInputs.count_filters(params[:params], params[:tag_id], params[:contact_type], params[:search])
+      params.except(:tag_id, :contact_type, :search).merge(params: filters)
+    end
+  end
+end