unisender-ruby 0.1.1 → 0.2.0

data/docs/usage.md

@@ -0,0 +1,144 @@
+# Using the client
+
+## Responses and failures
+
+Named operations return typed responses. Collections support `each`, `map`, and other `Enumerable` methods. Object results expose documented fields directly. `result` contains the typed value; `data` preserves the full upstream JSON object. `http_status`, `headers`, and `warnings` retain response metadata. Values are deeply immutable; use `result.to_h` for a mutable object copy. See [the 0.2 migration guide](migration-0.2.md).
+
+Collections also support `length`, `at`, slices, and `fetch` with a default or block.
+`send_sms(phone: [...], sender:, text:)` accepts phone arrays and always returns a receipt collection, including for one phone.
+Records provide `key?`, `keys`, `values`, and `fetch` with the same missing-value behavior as a Ruby Hash.
+Object responses forward these lookups. Record equality is class-sensitive; use `to_h` to compare with a Hash.
+Object responses expose `to_h`. `as_json` and `to_json` serialize the result payload, without HTTP metadata or the response envelope.
+Both serializers accept `only:` and `except:` field names. Filters select top-level fields on each record; unsupported options raise `ArgumentError`.
+Use `contact.email_address` and `contact.phone_number` for stable address readers; omitted contact details remain `nil`.
+
+Named methods use snake_case and reject unknown keywords. Optional `nil` values are omitted, preserving server defaults. API messages default to English; use `Client.new(api_key: ..., language: :ru)` for Russian. Message-level `lang:` is a separate setting.
+
+Campaign `Time` values use explicit UTC and minute precision. String timestamps retain the specified or account-default timezone.
+
+Library-detected input failures raise `ValidationError`, an `ArgumentError` subclass with `field`, `code`, and `operation`.
+Named calls reject incorrect scalar and collection types before networking.
+Use `client.validate!(:subscribe, email: "person@example.test", list_ids: [123])` to check arguments and encoding offline.
+Validation returns `true` or raises. It applies client defaults and consumes supplied import enumerables, but makes no requests.
+Known flags accept only booleans or 0/1. Template types and note ordering also accept documented Symbol choices.
+`send_email` requests detailed recipient acceptance by default; set `error_checking: false` for the legacy response or `nil` to omit it.
+Use `accepted_ids`, `accepted_recipients`, `rejected_recipients`, and `unknown_recipients` to inspect send outcomes.
+`reply_to:` and `priority:` merge with Hash headers; conflicting or multiline values are rejected.
+`images_as:` accepts `:attachments`, `:only_links`, or `:user_default` as well as their String forms.
+
+Use this error handler in your application's `request.rb`:
+
+```ruby
+begin
+  client.get_lists
+rescue Unisender::APIError => error
+  warn error.message
+  # Fix credentials, permissions, or parameters using error.code.
+rescue Unisender::HTTPError => error
+  warn error.message
+  # Check error.response.http_status and error.response.headers.
+rescue Unisender::TransportError, Unisender::InvalidResponseError => error
+  warn error.message
+  # Check service availability before deciding whether to repeat the operation.
+end
+```
+
+`APIError` also covers API failures returned with HTTP 200; an accompanying result is discarded. `HTTPError` covers non-2xx statuses, including redirects. `InvalidResponseError` covers malformed successful responses. `TimeoutError` is a `TransportError`. All derive from `Unisender::Error`.
+
+Error messages identify known operations and HTTP statuses or documented API codes. Unknown wire method names and unrecognized API codes are not copied into messages. `error.operation` is available separately. Credentials, request bodies, and contact data are omitted. Explicit accessors such as `error.details`, `error.response.data`, and `response.data` can contain private information. No request logging is enabled.
+
+A successful envelope does not mean every recipient succeeded. Inspect `send_email(error_checking: 1, ...)` recipient errors and import counters. A `BatchError` provides `completed_responses`, the zero-based, end-exclusive `failed_range`, and the original `error`. Accepted changes remain applied; do not repeat the whole input automatically. The [batch example](../examples/import.rb) shows how to inspect partial results.
+
+## Timeouts, retries, and pagination
+
+In `quickstart.rb`, replace the client construction with:
+
+```ruby
+client = Unisender::Client.new(
+  api_key: ENV.fetch("UNISENDER_API_KEY"),
+  open_timeout: 5, read_timeout: 60, write_timeout: 30,
+  max_retries: 2, max_elapsed: 60
+)
+```
+
+Those are the default transport timeouts in seconds. TLS certificates are verified and redirects are rejected. Connections are separate by default; `persistent: true` enables reuse. **Retries default to zero.** The opt-in policy retries only explicitly identified read-only operations, at most twice, with backoff, jitter, and `Retry-After`. Sends, mutations, imports, exports, events, and unknown methods are never retried automatically. The elapsed retry budget is not a hard request deadline; in-flight requests use transport timeouts.
+
+`each_page` and `each_*` helpers return lazy Enumerators. Consume them, or supply a block to a named iterator, to make requests. Batch command methods execute immediately and return a `BatchReport`. Stopping enumeration prevents subsequent requests. A fetched page exposes `each_page` and `auto_each`; ordinary `each` only visits that page. `each_page` yields responses, accepts a supported Ruby method name, and raises `PaginationError` at `max_pages`. `wait_for_task` polls an existing job; its deadline is checked between requests. See [helper limits and recovery behavior](api.md#convenience-operations) and [upstream rate limits](https://www.unisender.com/ru/support/api/common/api-limits/).
+
+All page iterators accept blocks. Fetched pages expose `offset`, `limit`, and `next_offset` for explicit checkpoints.
+Task handles provide `completed?`, `failed?`, and `pending?`. Calling `wait` on a completed handle returns it without another request.
+Waiting on a failed handle raises `TaskFailedError` immediately, preserving its response and task UUID.
+
+## Low-level access and types
+
+`client.request("getLists", params: {})` accepts exact upstream names. It handles authentication, encoding, and failures, but does not perform operation-specific conversions. Comma-separated fields must already be strings; nested arrays and hashes become bracketed form fields. Credentials and JSON format cannot be overridden.
+
+RBS signatures ship with the gem. `Response[Result]` describes a named operation's result; the low-level method keeps the general JSON type. Named results validate documented field shapes while retaining unknown fields. Unknown fields remain accessible through `response.data`. Consumer examples are checked with Steep alongside library code.
+
+## Configuration and application tests
+
+`Client.from_env` reads `UNISENDER_API_KEY` from the supplied environment. It does not load `.env`.
+Use `client.with(...)` to create an independent configuration variant.
+`message_defaults:` accepts only `sender_name`, `sender_email`, and `lang`; explicit call arguments take precedence.
+
+An optional `instrumentation:` callable receives operation, attempt, duration, HTTP status, outcome, error category, and upstream request ID when available.
+It receives no request payload. Exceptions raised by the callback do not change the operation's result.
+
+Errors expose `category`, `recovery_hint`, `request_id` when supplied, `transient?`, and `safe_to_retry?`.
+Use `error.diagnostics` for a frozen, payload-free Hash with known operation, field, HTTP, and recovery context.
+Validation and result-shape failures expose `path`, `expected_type`, `actual_type`, and `documentation_url` when available.
+A transient failure does not imply that repeating a mutation is safe.
+Import and send reports expose `complete?`, `partial?`, `uncertain?`, and `failures`.
+These describe acceptance, not final message delivery.
+
+Imports expose typed `row_warnings` separately from failures and envelope warnings.
+The `records:` input accepts arrays in documented list/tag cells and Time values in subscription-time cells.
+`unsubscribe(email: ..., list_ids: [...])` and `exclude(phone: ..., list_ids: [...])` provide explicit contact selectors.
+`get_contact_count(list_id:, contact_type: :email, search:, tag_id:)` builds filters; the existing `params:` form remains available separately.
+
+See [application testing](testing.md), [Rails integration](rails.md), and the [migration guide](migration-0.2.md).
+The [execution guide](execution.md) covers lazy consumption, checkpoints, shared request budgets, cancellation, and summary retention. The [webhook guide](webhooks.md) covers hook management and authenticated receivers. [Staging contract checks](live-contracts.md) are explicitly opt-in.
+
+Use `client.with_execution(timeout: 30, cancellation: token) { |scoped| ... }` for one cooperative budget across related operations. `token` is a `Unisender::CancellationToken`; calling `cancel` stops work at the next boundary. In-flight IO and callbacks are not interrupted.
+For large imports, `import_contacts_in_batches(records:, retention: :summary, on_progress:)` returns counts without retaining successful response bodies. Full report retention remains the default.
+
+## Optional workflow helpers
+
+Use connection reuse for repeated calls and close clients when their lifetime ends:
+
+`Unisender::Client.open(api_key: ..., persistent: true) { |client| ... }` closes owned resources when the block exits, including after an exception.
+It returns the block's result and never closes an injected transport.
+
+```ruby
+client = Unisender::Client.from_env(
+  persistent: true,
+  rate_limiter: Unisender::RateLimiter.unisender
+)
+begin
+  client.get_lists.each { |list| puts list.title }
+ensure
+  client.close
+end
+```
+
+Pacing is opt-in, process-local, and separate from retries. Share a limiter between clients that share an account budget. The built-in preset covers marketing requests; Event Tracking has a separate budget. An injected transport remains caller-owned. Create clients after forking where possible; persistent transports discard inherited connections on a PID change.
+
+Set `event_rate_limiter: Unisender::RateLimiter.new(global: [count, seconds])` to pace Event Tracking independently.
+Choose the event budget for your application; the library supplies no provider rate preset for this protocol.
+
+`Attachment.from_path(path)` and `Attachment.from_io(io, filename:)` read binary data into an immutable snapshot. Pass one attachment, an array, or the existing filename-to-bytes hash as `attachments:`. The helper never closes a caller-owned IO.
+
+Pass `max_bytes:` to bound attachment reads. Direct imports inspect at most 501 records; use batching for more than 500 records.
+
+`send_campaign(message: {...}, campaign: {...})` validates both steps before creating the message and returns `receipt.message` and `receipt.campaign`. If campaign creation fails, `CampaignWorkflowError#message_response` preserves the created message. The workflow cannot roll back account changes.
+
+Completed export tasks can stream into a caller-owned IO:
+
+```ruby
+completed = client.export_contacts(list_id: 123).wait
+File.open("contacts.csv", "wb") do |file|
+  completed.download_to(file, max_bytes: 20 * 1024 * 1024)
+end
+```
+
+Downloads are explicit, use a separate connection without API credentials, and accept only public HTTPS destinations on port 443. Redirects are rejected. Set a byte limit; `DownloadError#bytes_written` reports confirmed partial output, which remains in your IO. See [helper contracts](api.md#optional-workflow-helpers) for configuration and failure details.

data/docs/webhooks.md

@@ -0,0 +1,41 @@
+# Receiving UniSender webhooks
+
+Webhook delivery is separate from outbound `track_events`. Register a dedicated HTTPS receiver:
+
+```ruby
+client.set_hook(hook_url: "https://example.com/unisender",
+                events: { email_status: %w[ok_read ok_link_visited], subscribe: "*" })
+client.list_hooks.each { |hook| puts hook.id }
+client.remove_hook(hook_url: "https://example.com/unisender")
+```
+
+`set_hook` replaces the registration for the same URL. Its defaults are `event_format: :json_post_gzip`, `single_event: false`, and `status: :active`. Mutation methods return raw `Response` payloads because their success fields are not specified. The registration check sends an empty GET and expects HTTP 200. It does not authenticate an event.
+
+Read the request body once, impose a server-side request limit, then verify it before processing:
+
+```ruby
+require "unisender/webhooks"
+
+raw = request.body.read(1_048_577)
+notification = Unisender::Webhooks.verify(
+  body: raw, api_key: credentials.fetch(:unisender_api_key),
+  content_encoding: request.get_header("HTTP_CONTENT_ENCODING")
+)
+notification.users.each do |user|
+  user.events.each { |event| persist_event(user.login, event.to_h) }
+end
+```
+
+The verifier preserves unknown fields and accepts `events` or `Events` within each user, rejecting conflicting keys. It supports only the documented batched JSON format, including gzip. It bounds compressed input, decompressed input, nesting, and event count. Defaults are 1 MiB, 4 MiB, 64 levels, and 10,000 events. It rejects duplicate JSON keys and trailing compressed data. `WebhookError#reason` contains no payload data.
+
+Authentication follows the upstream MD5 procedure on the original decompressed JSON, replacing only the top-level auth value with the JSON-encoded key. Never parse and regenerate the JSON before verification. Authentication alone does not prevent replay. Deduplicate and process events idempotently in durable application storage. Return HTTP 200 only after durable acceptance; keep processing short. Delivery can repeat, and an unsuccessful receiver is retried before registration stops. Handle malformed data without logging bodies, API keys, or contact information.
+
+## Protocol security limitation
+
+The [supported webhook protocol](https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/) requires MD5 and documents no stronger signature mode. Replacing MD5 locally would reject valid notifications.
+
+This library accepts that protocol limitation. The exception covers only the digest in `Unisender::Webhooks.authenticate`, tracked by [CodeQL alert #3](https://github.com/svyatov/unisender-ruby/security/code-scanning/3). Its disposition is `won't fix`, not `false positive`. Other uses of weak cryptography remain subject to CodeQL checks.
+
+Require HTTPS, retain the request limits, and deduplicate events in application storage. These controls do not remove MD5's cryptographic limitations. Reassess the exception if UniSender introduces stronger webhook authentication.
+
+These contracts are based on [UniSender's webhook documentation](https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/) and offline fixtures. A designated test account and an authorized receiver are still required to verify live delivery.

data/examples/campaign.rb

@@ -5,9 +5,8 @@
 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")
+receipt = client.send_campaign(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>"
+                               })
+puts receipt.campaign.campaign_id

data/examples/campaign_lifecycle.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Requires the API key, list ID, sender email, test email, and ISO 8601 start time below.
+# Creates a message, sends a test, and schedules a campaign to consenting test recipients.
+# Stop on failure. Reconcile saved IDs before rerunning any mutation.
+require "unisender"
+
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+list_id = ENV.fetch("UNISENDER_LIST_ID")
+sender = ENV.fetch("UNISENDER_SENDER_EMAIL")
+test_email = ENV.fetch("UNISENDER_TEST_EMAIL")
+start_time = Time.iso8601(ENV.fetch("UNISENDER_START_TIME"))
+raise ArgumentError, "Choose a future start time" unless start_time > Time.now
+
+# 1. Creates message content, without launching the campaign.
+message = client.create_email_message(sender_name: "Example", sender_email: sender,
+                                      list_id:, subject: "Product news", body: "<p>Hello</p>")
+puts "Save message_id: #{message.message_id}"
+# 2. Reads the created content. Save the ID in application storage before continuing.
+draft = client.get_message(id: message.message_id)
+puts "Review subject: #{draft.subject}"
+# 3. Sends only to the explicit test address. The provider can require address verification.
+client.send_test_email(id: message.message_id, email: test_email)
+# 4. Schedules delivery to the list. Time is converted to explicit UTC, at minute precision.
+campaign = client.create_campaign(message_id: message.message_id, start_time:)
+puts "Save campaign_id: #{campaign.campaign_id}"
+# 5. Reads status once. Repeat only this read when observing the same campaign.
+puts "Campaign status: #{client.get_campaign_status(campaign_id: campaign.campaign_id).status}"

data/examples/check_connection.rb

@@ -9,7 +9,7 @@ abort "Set UNISENDER_API_KEY before running this example." if api_key.nil? || ap
 begin
   client = Unisender::Client.new(api_key:)
   response = client.get_lists
-  puts "Connected to UniSender: HTTP #{response.status}, #{response.result.size} list(s)."
+  puts "Connected to UniSender: HTTP #{response.http_status}, #{response.result.size} list(s)."
 rescue ArgumentError, Unisender::Error => e
   warn e.message
   exit 1

data/examples/events.rb

@@ -9,7 +9,7 @@ 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}" }
+                                 ]).each { |response| puts "Recorded batch: HTTP #{response.http_status}" }
 rescue Unisender::BatchError => e
   warn "Review events #{e.failed_range}; completed batches: #{e.completed_responses.size}"
   failure = e.error

data/examples/export.rb

@@ -1,11 +1,25 @@
 # 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.
+# Requires UNISENDER_API_KEY, UNISENDER_LIST_ID, UNISENDER_EXPORT_STATE,
+# and UNISENDER_EXPORT_PATH. Starts or resumes an export job.
 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}"
+state = ENV.fetch("UNISENDER_EXPORT_STATE")
+destination = ENV.fetch("UNISENDER_EXPORT_PATH")
+if File.exist?(state)
+  job = client.get_task_result(task_uuid: File.read(state).strip)
+else
+  job = client.export_contacts(list_id: ENV.fetch("UNISENDER_LIST_ID"))
+  File.open("#{state}.tmp", "w", 0o600) { |file| file.write(job.task_uuid) }
+  File.rename("#{state}.tmp", state)
+end
+# A crash before saving the UUID requires reconciliation before starting another job.
+completed = job.wait
+File.open("#{destination}.part", "wb", 0o600) do |file|
+  completed.download_to(file, max_bytes: 100 * 1024 * 1024)
+end
+File.rename("#{destination}.part", destination)
+File.delete(state)
+puts "Export saved"
+# On failure, keep the UUID. A retry truncates .part and downloads the same job.

data/examples/import.rb

@@ -6,12 +6,13 @@ 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}" }
+    records: [{ email: ENV.fetch("UNISENDER_CONTACT_EMAIL"), Name: "Example" }]
+  ).each { |response| puts "Imported batch: HTTP #{response.http_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."
+    e.report.failures.each { |failure| warn "Rejected row #{failure.index}: #{failure.code}" }
   end
   warn e.error.message
   # Stop here. Reconcile accepted rows before building a new input; never replay all rows blindly.

data/examples/import_recovery.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "unisender"
+require "digest"
+
+# Application-owned file checkpoint. Use a private directory and one worker per state file.
+class RecoverableImport
+  def initialize(client, state_path)
+    @client = client
+    @state_path = state_path
+  end
+
+  def run(rows, batch_size: 500)
+    raise ArgumentError, "Invalid batch size" unless (1..500).cover?(batch_size)
+
+    state = read_state(rows)
+    offset = resume_index(state, rows.size)
+    rows.drop(offset).each_slice(batch_size) { |batch| offset = import_batch(batch, state, offset) }
+    offset
+  end
+
+  private
+
+  def resume_index(state, size)
+    raise "Reconcile the recorded in-flight rows before resuming" if state["in_flight"]
+
+    offset = state.fetch("next_index")
+    raise "Invalid checkpoint index" unless offset.is_a?(Integer) && (0..size).cover?(offset)
+
+    offset
+  end
+
+  def import_batch(batch, state, offset)
+    state["in_flight"] = batch.map { |row| row.fetch("id") }
+    save(state) # Durable intent precedes the remote mutation.
+    records = batch.map { |row| row.fetch("fields") }
+    import_records(records)
+    state["next_index"] = offset + batch.size
+    state.delete("in_flight")
+    save(state) # Crash before this write requires reconciliation, not replay.
+    offset + batch.size
+  end
+
+  def import_records(records)
+    response = @client.import_contacts(records:).raise_for_partial_failure!
+    raise Unisender::PartialFailure, response unless response.total == records.size
+  end
+
+  def read_state(rows)
+    digest = Digest::SHA256.hexdigest(JSON.generate(rows))
+    return { "source_digest" => digest, "next_index" => 0 } unless File.exist?(@state_path)
+
+    state = JSON.parse(File.read(@state_path)) # : Unisender::json
+    raise "Invalid checkpoint" unless state.is_a?(Hash)
+    raise "Source changed; reconcile before resuming" unless state["source_digest"] == digest
+
+    state
+  end
+
+  def save(state)
+    temporary = "#{@state_path}.#{Process.pid}.tmp"
+    File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+      file.write(JSON.generate(state))
+      file.flush
+      file.fsync
+    end
+    File.rename(temporary, @state_path)
+    File.open(File.dirname(@state_path), &:fsync)
+  end
+end

data/examples/quickstart.rb

@@ -3,5 +3,5 @@
 require "unisender"
 
 client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
-client.get_lists.result.each { |list| puts list.fetch("title") }
+client.get_lists.each { |list| puts list.title }
 # Example output for a list named News: News

data/examples/subscribe.rb

@@ -7,6 +7,6 @@ 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") }
+  email: ENV.fetch("UNISENDER_CONTACT_EMAIL")
 )
-puts response.result.fetch("person_id")
+puts response.person_id

data/lib/unisender/acceptance.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Unisender
+  AcceptanceEvent = Data.define(:operation, :outcome, :input_count, :accepted_count, :rejected_count,
+                                :unknown_count, :row_warning_count, :request_id)
+
+  # Acceptance accounting is separate from HTTP and request-attempt outcomes.
+  module Acceptance
+    def self.input_count(operation, params)
+      case operation
+      when "sendEmail" then params[:cc] ? 2 : 1
+      when "sendSms"
+        phone = params[:phone]
+        phone.split(",").size if phone.is_a?(String)
+      when "importContacts"
+        data = params[:data]
+        data.size if data.is_a?(Array)
+      end
+    end
+
+    def self.event(operation, count, response, error)
+      accepted, rejected, unknown = bounded_counts(count, counts(count, response, error))
+      request_id = response&.headers&.[]("x-request-id") || (error.is_a?(Error) ? error.request_id : nil)
+      AcceptanceEvent.new(operation: Error.safe_operation(operation) || "request",
+                          outcome: state(response, error, unknown), input_count: count,
+                          accepted_count: accepted, rejected_count: rejected, unknown_count: unknown,
+                          row_warning_count: warning_count(response), request_id:)
+    end
+
+    def self.bounded_counts(count, values)
+      return [nil, nil, nil] if values.compact.any?(&:negative?)
+
+      accepted, rejected, unknown = values
+      known = accepted.to_i + rejected.to_i + unknown.to_i
+      known > count ? [nil, nil, nil] : values
+    end
+
+    def self.warning_count(response)
+      return response.row_warnings.size if response.is_a?(ImportResponse)
+
+      response ? 0 : nil
+    end
+
+    def self.counts(count, response, error)
+      case response
+      when SendResponse then send_counts(count, response)
+      when ImportResponse then import_counts(count, response)
+      when EventResponse then [count, 0, 0]
+      when CollectionResponse then [response.size, 0, [count - response.size, 0].max]
+      else
+        error.is_a?(EventError) && error.http_status == 401 ? [0, count, 0] : [nil, nil, nil]
+      end
+    end
+
+    def self.send_counts(count, response)
+      accepted = response.email_id ? count : response.accepted_recipients.size
+      rejected = response.rejected_recipients.size
+      [accepted, rejected, [count - accepted - rejected, response.unknown_recipients.size, 0].max]
+    end
+
+    def self.import_counts(count, response)
+      total = response.total
+      accepted = total && total >= response.invalid ? total - response.invalid : nil
+      [accepted, response.invalid, total ? [count - total, 0].max : nil]
+    end
+
+    def self.state(response, error, unknown)
+      return failure_state(error) if error
+      return :uncertain unless unknown&.zero?
+      return result_state(response) if response.is_a?(OutcomeResponse)
+
+      :complete
+    end
+
+    def self.failure_state(error)
+      error.is_a?(EventError) && error.http_status == 401 ? :rejected : :uncertain
+    end
+
+    def self.result_state(response)
+      return :complete if response.complete?
+      return :partial if response.partial?
+
+      :rejected
+    end
+
+    def self.emit(callback, event)
+      callback.call(event)
+    rescue StandardError
+      nil
+    end
+  end
+
+  # Optional callbacks expose acceptance independently of request attempts.
+  class Client
+    private
+
+    def observe_acceptance(operation, count, response, error)
+      callback = @configuration.acceptance_instrumentation
+      return unless callback && count
+
+      Acceptance.emit(callback, Acceptance.event(operation, count, response, error))
+    end
+  end
+end

data/lib/unisender/attachment.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Unisender
+  # A snapshot of binary data; reading an IO never transfers ownership.
+  class Attachment
+    attr_reader :filename, :bytes
+
+    def initialize(filename:, bytes:)
+      if filename.empty? || filename.match?(/[\[\]\r\n\0]/)
+        raise ArgumentError, "Attachment filename must be nonempty without brackets or line breaks"
+      end
+
+      @filename = filename.dup.freeze
+      @bytes = bytes.b.freeze
+      freeze
+    end
+
+    def self.from_path(path, filename: File.basename(path), max_bytes: nil)
+      File.open(path, "rb") { |io| from_io(io, filename:, max_bytes:) }
+    rescue SystemCallError
+      raise ArgumentError, "Attachment file could not be read", cause: nil
+    end
+
+    def self.from_io(io, filename:, max_bytes: nil)
+      size = read_size(max_bytes)
+      bytes = size ? io.read(size) : io.read
+      raise ArgumentError, "Attachment IO must return a string" unless bytes.is_a?(String)
+      raise ValidationError.new(field: "attachments", code: :too_large) if max_bytes && bytes.bytesize > max_bytes
+
+      new(filename:, bytes:)
+    end
+
+    def self.read_size(max_bytes)
+      return nil if max_bytes.nil?
+      unless max_bytes.is_a?(Integer) && max_bytes.positive?
+        raise ValidationError.new(field: "max_bytes", code: :invalid_range)
+      end
+
+      max_bytes + 1
+    end
+    private_class_method :read_size
+
+    def inspect
+      "#<Unisender::Attachment>"
+    end
+  end
+end

data/lib/unisender/batch_report.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Completed responses can be inspected repeatedly without repeating requests.
+  class BatchReport
+    include Enumerable
+
+    attr_reader :responses
+
+    def initialize(responses, error: nil, failed_range: nil, offsets: nil)
+      @responses = responses.dup.freeze
+      @error = error
+      @failed_range = failed_range
+      @offsets = offsets&.dup&.freeze
+      freeze
+    end
+
+    def each(&block)
+      return responses.each unless block
+
+      responses.each(&block)
+    end
+
+    def complete?
+      @error.nil?
+    end
+
+    def completed_batches
+      responses.size
+    end
+
+    def partial?
+      !complete? && (!responses.empty? || failed_response&.partial? == true)
+    end
+
+    def uncertain?
+      error = @error
+      case error
+      when nil, ArgumentError then false
+      when PartialFailure
+        response = failed_response
+        response.nil? || response.uncertain?
+      when EventError then error.report.uncertain?
+      else true
+      end
+    end
+
+    def failures
+      response = failed_response
+      return [] unless response
+
+      offset = @failed_range&.begin || 0
+      response.failures.map { |failure| failure.with_offset(offset) }
+    end
+
+    def row_warnings
+      # @type var warnings: Array[Failure]
+      warnings = []
+      # @type var offset: Integer?
+      offset = 0
+      offsets = @offsets
+      responses.each_with_index do |response, index|
+        next unless response.is_a?(ImportResponse)
+
+        warnings.concat(warning_rows(response, offsets ? offsets.fetch(index) : offset))
+        count = response.total
+        offset = offset && count ? offset + count : nil
+      end
+      warnings + failed_warnings
+    end
+
+    def total
+      results = import_results
+      return nil unless results
+
+      totals = results.map(&:total)
+      totals.include?(nil) ? nil : totals.compact.sum
+    end
+
+    def invalid
+      import_results&.sum(&:invalid)
+    end
+
+    private
+
+    def failed_warnings
+      failed = failed_response
+      failed.is_a?(ImportResponse) ? warning_rows(failed, @failed_range&.begin) : []
+    end
+
+    def warning_rows(response, offset)
+      response.row_warnings.map do |warning|
+        offset ? warning.with_offset(offset) : Failure.new(warning.to_h.merge("index" => nil))
+      end
+    end
+
+    def failed_response
+      error = @error
+      return nil unless error.is_a?(PartialFailure)
+
+      response = error.response
+      response if response.is_a?(OutcomeResponse)
+    end
+
+    def import_results
+      return nil if @error && !failed_response
+
+      all = responses.dup
+      failed = failed_response
+      all << failed if failed
+      results = all.filter_map { |response| response.result if response.is_a?(ImportResponse) }
+      results if results.size == all.size
+    end
+  end
+end