unisender-ruby 0.1.1 → 0.2.0

data/docs/execution.md

@@ -0,0 +1,89 @@
+# Consumption, ownership, and recovery
+
+`client.get_lists.each` iterates the fetched response without a network request. An all-page iterator explicitly requests more pages:
+
+```ruby
+client.each_message(date_from: "2026-01-01", date_to: "2026-01-02")
+      .lazy.map(&:id).take(10).force
+```
+
+`map` alone consumes an entire Enumerable immediately. Use `.lazy.map` for early stopping, or `.to_a` when you intend to retain every item. Each new enumeration of a page iterator starts another read sequence. Page offsets do not promise a stable server snapshot.
+
+```ruby
+client.each_page(:get_messages, date_from: "2026-01-01", date_to: "2026-01-02") do |page|
+  process_page(page)
+  save_next_offset(page.next_offset) # Save only after processing succeeds.
+end
+```
+
+Batch commands such as `import_contacts_in_batches` execute immediately. `each_import_batch` and `each_event_batch` execute when consumed. Re-enumerating them repeats mutations if the source can be replayed. A non-rewindable source may instead be exhausted. Do not use enumeration as a retry mechanism.
+
+The [import example](../examples/import.rb) uses record hashes and reports failed source ranges. Persist the source and reconcile accepted rows before retrying an ambiguous failure. Row indices are zero-based. Do not interpret an HTTP success as complete acceptance or as recipient delivery.
+
+The [export example](../examples/export.rb) saves the task UUID, resumes the saved job, bounds the download, and renames a completed `.part` file. Use private paths on the same filesystem for atomic renames. State persistence and starting a remote job cannot be one atomic transaction: if the process stops before the UUID is stored, reconcile the job before starting another. A partial file contains private contact data and needs the same access controls as the final file.
+
+## Shared request budgets
+
+One `RateLimiter` coordinates clients in one Ruby process. It cannot coordinate worker processes, other applications using the same key, or callers sharing an egress IP. Route those calls through one application-owned request worker or gateway that serializes acquisition against a shared store and accounts for every request. Keep its policy aligned with the [upstream limits](https://www.unisender.com/ru/support/api/common/api-limits/).
+
+Give each worker an explicit client and close it when the worker stops. Inject the client into application services. Do not construct persistent clients before forking. Keep contact data and raw error details out of logs; log the operation, category, and request ID instead.
+
+### Client ownership
+
+| Client or resource | Lifetime and sharing |
+| --- | --- |
+| Default client | Creates a separate connection for each request; close it when its application owner stops. |
+| Persistent client | Serializes requests on its built-in transport. Sharing one client does not increase request concurrency. |
+| `client.with(...)` | Creates an independent client lifetime. An injected transport remains shared and caller-owned. |
+| `with_execution` client | Borrows its parent's transport and expires when the block ends. Close the parent at its normal lifetime boundary. |
+| Injected transports and callbacks | The application supplies any synchronization their implementation needs. |
+| Forked worker | Construct clients after forking. Built-in persistent transports discard inherited connections on a PID change. |
+
+Both API protocols send a User-Agent containing the gem and Ruby versions, without account or host information.
+
+## Cooperative execution scopes
+
+```ruby
+token = Unisender::CancellationToken.new
+client.with_execution(timeout: 30, cancellation: token,
+                      instrumentation: ->(event) { record_timing(event.kind, event.duration) }) do |scoped|
+  scoped.each_import_batch(records: records) { |response| process_result(response) }
+end
+# Another thread can call token.cancel.
+```
+
+The timeout is one monotonic budget for the scope. Requests, retry delays, pacing, task polling, and batch boundaries use that budget. Nested scopes also obey their parent's deadline and cancellation. The scoped client borrows the parent's transport; closing it does not close the parent. Scoped clients and derived clients cannot be used after the block ends.
+
+Cancellation and deadlines are cooperative. They do not forcibly interrupt an in-flight request, callback, or custom transport. Built-in downloads check between streamed chunks and preserve confirmed bytes in the error. Successful in-flight mutations return their result; the next boundary stops further work. Built-in socket timeouts are reduced to the remaining budget before IO. Do not use this scope as a hard wall-clock timeout. `CancelledError` and `DeadlineExceededError` have separate categories. Batch failures retain completed work, including when cancellation occurs before another batch.
+
+The scope's instrumentation emits payload-free `ExecutionEvent` values for `workflow`, `retry_wait`, `rate_limit_wait`, and `poll_wait`. Existing request instrumentation measures individual network attempts and includes the upstream request ID when available. Observer exceptions do not change the operation's result. Progress callbacks are application work, so their exceptions stop the job with completed-work context.
+
+## Acceptance metrics
+
+Pass `acceptance_instrumentation: ->(event) { record_acceptance(event) }` when constructing a client.
+The callback receives an immutable `AcceptanceEvent` for each attempted named send, import, or Event Tracking request.
+Reads and offline validation do not emit acceptance events.
+
+Events contain `operation`, `outcome`, `input_count`, `accepted_count`, `rejected_count`, `unknown_count`, `row_warning_count`, and `request_id`.
+Counts unavailable from the response are `nil`. They are not inferred from HTTP success.
+An Event Tracking HTTP 400 response can mean partial acceptance, with unknown counts.
+Transport failures also leave acceptance counts unknown. HTTP 401 rejects the event batch.
+Outcomes are `:complete`, `:partial`, `:rejected`, or `:uncertain`.
+
+Acceptance describes provider acknowledgement, not delivery to a recipient.
+Request `instrumentation:` separately reports network attempts and can report success when acceptance is rejected.
+Callbacks receive no payload, contact address, credential, or response body. Callback exceptions do not change operation results.
+
+## Retaining large jobs
+
+Full `BatchReport` history remains the default. For large imports or event streams, select `retention: :summary` on either an immediate or lazy batch helper. Immediate calls return a non-enumerable `BatchSummary`; lazy calls still yield each response but retain no successful response bodies internally.
+
+```ruby
+summary = client.import_contacts_in_batches(
+  records: records, retention: :summary,
+  on_progress: ->(progress) { save_checkpoint(progress.next_index) }
+)
+puts summary.completed_items
+```
+
+`BatchProgress` snapshots contain completed batch and input counts, next source index, invalid count, warning count, and the current `response`. Counts describe completed batches. Summary failures retain the failed response and its row details. Successful warning details and response payloads are discarded, so persist anything you need in the response or progress callback. Retaining progress snapshots also retains their responses. Applications can still retain unbounded data themselves, for example by calling `to_a` on a lazy batch helper.

data/docs/import-recovery.md

@@ -0,0 +1,41 @@
+# Recovering imports
+
+Keep source rows and application IDs stable for the whole job. Store them in private application storage.
+The [RecoverableImport example](../examples/import_recovery.rb) accepts rows with separate application IDs and API fields.
+It persists the source checksum, next completed index, and IDs of the in-flight rows.
+
+Run it from an application file with an injected client:
+
+```ruby
+require "unisender"
+require_relative "import_recovery"
+
+rows = [
+  { "id" => "customer-42", "fields" => { "email" => "person@example.test", "Name" => "Example" } }
+]
+client = Unisender::Client.from_env
+completed = RecoverableImport.new(client, "/private/job-42.json").run(rows)
+puts "Completed rows: #{completed}"
+```
+
+Use a writable private directory on a filesystem that supports atomic rename. Only one worker may own the checkpoint.
+For concurrent workers or transactional guarantees, use a database job row and lock, as in the [Rails integration](rails.md).
+Every row must contain the same API field keys. Application IDs are not sent to UniSender.
+
+The example writes intent before sending each batch. It advances the completed index only after complete acceptance.
+The response must report zero invalid rows and a total equal to the submitted batch size.
+Missing or inconsistent totals preserve the in-flight marker for reconciliation.
+A restart with an in-flight marker refuses to send. This covers a timeout, partial response, callback failure, or process crash after sending.
+
+1. Read the persisted application IDs and the original source. Keep the source order unchanged.
+2. Inspect `PartialFailure#response` privately for known acceptance and failure details, when available. Row positions are zero-based within that request.
+3. Reconcile every in-flight row against the account. A missing response does not prove rejection.
+4. Record the reconciliation decision in application storage. Build a separate job for confirmed rejected or unconsumed rows.
+
+Never clear the marker solely because a request failed. A completed batch can already have changed the account.
+Source checksums detect accidental edits; they do not provide remote idempotency.
+For `BatchError`, `failed_range` identifies source positions, not safe retry input. `error.diagnostics` is safe for logs; raw reports contain contact data.
+
+Application job IDs provide correlation across logs, checkpoints, and manual reconciliation.
+For direct email, carry an application reference in documented metadata and retain returned message IDs.
+Do not treat `ref_key` as an idempotency guarantee.

data/docs/live-contracts.md

@@ -0,0 +1,34 @@
+# Staging contract checks
+
+Offline fixtures establish deterministic behavior. They do not establish the response shapes or permissions of a live account. The repository has not run this harness against an authorized account.
+
+Obtain explicit permission and use a designated test account before running either command. Set `UNISENDER_API_KEY` privately in your environment. Do not save it in a fixture or command transcript.
+
+```sh
+UNISENDER_LIVE=1 UNISENDER_LIVE_MODE=read bundle exec ruby -r ./scripts/live_contracts -e 'LiveContracts.run(ENV, $stdout)'
+```
+
+Read mode requests lists, fields, and tags. Mutation mode creates one randomly named empty list, reads it back, and deletes that exact list in `ensure`:
+
+```sh
+UNISENDER_LIVE=1 UNISENDER_LIVE_MODE=mutation bundle exec ruby -r ./scripts/live_contracts -e 'LiveContracts.run(ENV, $stdout)'
+```
+
+Record the date, Ruby version, phase, service environment, and observed contract failures. Keep response bodies private. An interrupted process can leave its created list behind; reconcile that list before rerunning. The harness does not send messages, change contacts, register webhooks, or validate webhook delivery. Those need a separately approved account scenario and receiver.
+
+## Follow-up evidence gates
+
+These scenarios remain pending explicit authorization and a designated test account.
+Approve the exact sender, recipients, lists, and receiver before any send or contact mutation.
+
+| Case | Approved action needed | Evidence to retain |
+| --- | --- | --- |
+| L1 | Run the read-only harness | Successful typed results, HTTP status, tested account environment |
+| L2 | Create and delete one empty test list | Exact created ID and confirmed cleanup |
+| L3 | Schedule one message with an offset Time | Stored UTC minute, campaign ID, account timezone, final cancellation or completion |
+| L4 | Send SMS to one and multiple owned test numbers | Object/array wire cardinality and receipt IDs |
+| L5 | Submit a controlled partially invalid email/import batch | Accepted/rejected/unknown counts, warning paths, zero automatic replay |
+| L6 | Register a temporary HTTPS receiver and trigger an owned test delivery | Authentication, duplicate handling, status projection, registration cleanup |
+
+Record timestamps and library/Ruby versions. Retain only sanitized findings in this repository.
+Keep raw provider responses in private test storage. A green offline suite does not close these gates.

data/docs/migration-0.2.md

@@ -0,0 +1,129 @@
+# Migrating to 0.2
+
+All changes on this branch remain unreleased. Execution scopes, summary retention, and webhooks are opt-in. `RequestEvent` adds a `request_id` field. Full batch history remains the default; summary mode discards successful payloads and successful row-warning details. See [execution](execution.md) and [webhooks](webhooks.md).
+
+Named operations return typed records and collections. `request` retains raw JSON results.
+
+## Result access
+
+`send_sms` always returns a collection. Replace `response.sms_id` with `response.fetch(0).sms_id` for a single recipient.
+Phone arrays are accepted; the raw upstream object or array remains available through `response.data`.
+
+`JSON.generate(response)` serializes the typed payload. Use `response.data` when you need the upstream envelope.
+Collections support slices and fetch defaults; object responses provide `to_h`.
+`as_json` and `to_json` honor top-level `only:` and `except:` filters and reject unsupported options.
+Contact address strings are available through `email_address` and `phone_number`, independent of nested detail shapes.
+
+```ruby
+# Before
+client.get_lists.result.each { |list| puts list.fetch("title") }
+client.create_list(title: "News").result.fetch("id")
+
+# After
+client.get_lists.each { |list| puts list.title }
+client.create_list(title: "News").id
+```
+
+Use `response.result` for the typed result and `response.data` for the original JSON envelope.
+Records retain string-key lookup and unknown fields. `to_h` returns a detached mutable copy.
+Record equality requires the same concrete class. Use `to_h` when comparing a record with a Hash.
+Equivalent records work as Hash keys and in Sets. Object responses also expose `key?`, `keys`, and `values`.
+
+## HTTP metadata
+
+Replace `response.status` with `response.http_status` when reading the HTTP code.
+`response.status` exposes a documented result status when the operation supplies one.
+Headers and warnings retain their existing names.
+
+## Predicates and singular results
+
+Use `contact_in_lists?` in conditionals. It returns a boolean and accepts `condition: :any` or `:all`.
+The response-returning `is_contact_in_lists` method remains available.
+
+`get_message(id:)` returns one message. Empty results raise `NotFoundError`; multiple results raise `InvalidResponseError`.
+Count fields use integers. Tabular visited-link results become enumerable records keyed by the returned column names.
+
+## Execution and pagination
+
+Page iterators now execute supplied blocks. Avoid passing a block unless you intend to consume the iterator immediately.
+Successful pages expose checkpoint metadata through `offset`, `limit`, and `next_offset`.
+Completed task handles return immediately from `wait`; a supplied callback receives the existing handle once.
+Failed handles also invoke the callback once, then raise `TaskFailedError` without another request.
+
+`import_contacts_in_batches` and `track_events_in_batches` execute immediately and return a `BatchReport`.
+Use `each_import_batch` and `each_event_batch` for lazy execution. Each accepts a block or returns an Enumerator.
+Reading a report repeatedly does not repeat requests.
+
+Named paginated reads request 100 items unless you supply `limit`.
+Use a fetched page's `each_page` or `auto_each` to continue from that page without refetching it.
+Named iterators such as `each_message` yield typed items across pages and accept a block.
+Invalid pagination arguments raise when constructing the iterator. HTTP requests remain lazy.
+Pagination errors expose `next_offset` and `completed_pages` for recovery. Direct paginated reads now reject invalid limits and offsets before making requests.
+
+## Inputs and tasks
+
+Named methods reject wrong scalar and collection types before a request. Use arrays or comma-separated strings for list IDs and field IDs.
+`client.validate!(operation, **arguments)` checks a named request, Event Tracking, or a campaign workflow without networking.
+It applies the same defaults and structural rules as execution. Import validation consumes its source; recreate an enumerable before sending.
+
+Campaign `Time` inputs use UTC with `timezone: "UTC"`. Seconds are truncated to the API's minute precision.
+Conflicting timezone arguments raise `ValidationError`. String inputs retain their explicit or account-default timezone.
+
+Named flags reject values outside booleans and 0/1 before networking. Known closed choices reject unsupported values.
+Library validation failures expose structured fields through `ValidationError`, while remaining rescuable as `ArgumentError`.
+`error.diagnostics` provides safe structured context for validation, transport, API, task, and batch failures.
+Paths identify documented fields and row positions. Dynamic field names are masked; raw payload access remains explicit.
+`send_email` defaults `error_checking` to true. Use recipient results for IDs; explicit false retains the legacy format.
+`accepted_ids` works with both formats. Recipient views retain rejected and unknown outcomes separately.
+Named `reply_to:` and `priority:` headers reject conflicts. Unsupported `images_as` values fail locally.
+List/tag arrays in import records become comma-separated scalar cells. Subscription-time arrays retain their list-ID order.
+
+Supply `email:` directly to `subscribe`, or continue using `fields:`.
+Subscription modes accept `:request_confirmation`, `:already_confirmed`, and `:confirm_if_needed`.
+Overwrite modes accept `:preserve`, `:replace`, and `:update`. Numeric modes retain their meanings.
+
+Imports accept `records:` with consistent keys, including `email`. This input is mutually exclusive with `field_names:` and `data:`.
+Record key order may differ; the first record determines column order. Missing columns must be supplied explicitly.
+Arrays validate before sending. Streaming input validates as consumed.
+
+Timestamp arguments accept `Time` and convert it to the operation's UTC format. String inputs pass through unchanged.
+`ValidationError` provides `field`, `code`, and optional `operation` without including private values.
+
+Export and delivery-report responses are task handles. Call `job.wait` explicitly to poll.
+A block passed to `wait` receives each observed state. Polling deadlines retain the last response and task UUID. Request failures during polling preserve their original exception class and add `task_uuid` and `last_response`.
+
+## Partial success
+
+Import, send, and event responses expose `complete?`, `partial?`, `uncertain?`, and `failures`.
+These describe request acceptance, not final message delivery. Call `raise_for_partial_failure!` to reject incomplete acceptance explicitly.
+
+`BatchError#report` retains completed responses, known import totals, and failures with global input indices.
+Unknown acceptance remains unknown; the client does not count an uncertain request as rejected.
+Event batches respect the encoded payload limit as well as the event-count limit.
+Streaming input failures retain completed batches. No failed request or input chunk is replayed automatically.
+
+## Configuration and diagnostics
+
+Pass timeout and retry options directly to `Client.new`, or retain explicit transport and policy objects.
+Combining an explicit object with its construction options raises `ArgumentError`.
+`Client.from_env` reads the API key without loading files. `client.with(...)` leaves the original unchanged.
+
+`message_defaults` supplies sender name, sender email, and message language for message creation and direct email sends.
+Explicit arguments override defaults; explicit `nil` suppresses a default.
+
+Use `error.category`, `error.recovery_hint`, and `error.request_id` for diagnosis.
+`error.transient?` describes the failure. `error.safe_to_retry?` also checks the operation.
+Neither enables retries automatically.
+
+The optional instrumentation callback receives safe metadata for each attempt.
+See [application testing](testing.md) for deterministic responses and failure scenarios.
+
+## Optional helpers
+
+Use `persistent: true` for connection reuse and `client.close` when the client is no longer needed.
+An injected transport remains caller-owned. Request pacing is opt-in through `rate_limiter:` and is independent of retry settings.
+
+
+Attachments accept `Attachment.from_path`, `Attachment.from_io`, one attachment, or an array, alongside existing hashes.
+`send_campaign(message:, campaign:)` returns both responses and retains a created message if the campaign step fails.
+Completed tasks expose `download_to(io, max_bytes:)`. Downloads never happen automatically; errors retain confirmed partial byte counts.

data/docs/rails.md

@@ -0,0 +1,248 @@
+# Rails integration
+
+This example connects a background import, durable recovery state, and an authenticated delivery receiver.
+The gem has no Rails dependency. Add it to your application as described in the [README](../README.md).
+The example uses Rails 8.1 and a database with transactions and unique indexes.
+
+## Store recovery and delivery state
+
+Add `db/migrate/20261026000000_create_unisender_state.rb`, then run `bin/rails db:migrate`:
+
+<!-- file: db/migrate/20261026000000_create_unisender_state.rb -->
+```ruby
+class CreateUnisenderState < ActiveRecord::Migration[8.1]
+  def change
+    create_table :import_runs do |t|
+      t.json :source, null: false
+      t.integer :next_index, null: false, default: 0
+      t.json :in_flight
+      t.string :status, null: false, default: "ready"
+      t.json :diagnostics
+    end
+    create_table :delivery_events do |t|
+      t.string :fingerprint, null: false
+      t.string :account, null: false
+      t.json :payload, null: false
+      t.datetime :processed_at
+    end
+    add_index :delivery_events, :fingerprint, unique: true
+    create_table :email_deliveries do |t|
+      t.string :account, null: false
+      t.string :email_id, null: false
+      t.string :status
+      t.datetime :observed_at
+    end
+    add_index :email_deliveries, [:account, :email_id], unique: true
+  end
+end
+```
+
+Add these models to `app/models`:
+
+<!-- file: app/models/import_run.rb -->
+```ruby
+class ImportRun < ApplicationRecord
+  attr_readonly :source
+end
+```
+
+<!-- file: app/models/delivery_event.rb -->
+```ruby
+class DeliveryEvent < ApplicationRecord
+end
+```
+
+<!-- file: app/models/email_delivery.rb -->
+```ruby
+class EmailDelivery < ApplicationRecord
+end
+```
+
+Store source rows as `{"id" => "customer-42", "fields" => {"email" => "person@example.test"}}`.
+Keep all row fields consistent. Application IDs remain local; only `fields` are sent.
+Do not edit an import's source after creating it.
+
+## Import through an injected client
+
+Add `app/services/import_processor.rb`:
+
+<!-- file: app/services/import_processor.rb -->
+```ruby
+class ImportProcessor
+  def initialize(run, client:)
+    @run, @client = run, client
+  end
+
+  def call
+    while (work = claim)
+      batch, offset = work
+        response = @client.import_contacts(records: batch.map { |row| row.fetch("fields") }).raise_for_partial_failure!
+        raise Unisender::PartialFailure, response unless response.total == batch.size
+      @run.with_lock do
+        @run.update!(next_index: offset + batch.size, in_flight: nil, status: "ready")
+      end
+    end
+  rescue Unisender::Error => error
+    @run.update!(status: "needs_review", diagnostics: error.diagnostics)
+    raise
+  end
+
+  private
+
+  def claim
+    @run.with_lock do
+        raise "Reconcile in-flight rows before resuming" if @run.in_flight
+      batch = @run.source.slice(@run.next_index, 500)
+      if batch.empty?
+        @run.update!(status: "completed")
+        nil
+      else
+        @run.update!(status: "running", in_flight: batch.map { |row| row.fetch("id") })
+        [batch, @run.next_index]
+      end
+    end
+  end
+end
+```
+
+The claim transaction commits before the network call. A crash leaves `in_flight` intact.
+A duplicate job cannot send that batch again. A completed batch advances the checkpoint in another transaction.
+Never wrap the whole import in a database transaction, because rollback would erase the recovery marker.
+Keep each job's source and checkpoints on the primary database, not an eventually consistent replica.
+
+Add `app/jobs/import_contacts_job.rb`:
+
+<!-- file: app/jobs/import_contacts_job.rb -->
+```ruby
+class ImportContactsJob < ApplicationJob
+  def perform(run_id)
+    Unisender::Client.open(api_key: Rails.application.credentials.fetch(:unisender_api_key)) do |client|
+      ImportProcessor.new(ImportRun.find(run_id), client: client).call
+    end
+  end
+end
+```
+
+Start the job from application code with `ImportContactsJob.perform_later(run.id)`.
+Use your application's durable Active Job backend. Do not configure automatic mutation retries.
+If a backend redelivers a crashed job, the persisted marker stops the remote call.
+Reconcile marked rows using the [import recovery procedure](import-recovery.md), then create a separate job for safe remaining work.
+`diagnostics` contains safe metadata; `source`, `in_flight`, and response payloads are private application data.
+
+## Authenticate and persist webhook events
+
+Add this route inside `Rails.application.routes.draw` in `config/routes.rb`:
+
+```ruby
+match "/unisender", to: "unisender_webhooks#receive", via: [:get, :post]
+```
+
+Add `app/controllers/unisender_webhooks_controller.rb`:
+
+<!-- file: app/controllers/unisender_webhooks_controller.rb -->
+```ruby
+require "unisender/webhooks"
+
+class UnisenderWebhooksController < ActionController::API
+  def receive
+    return head :ok if request.get?
+    notification = Unisender::Webhooks.verify(
+      body: request.body.read(1_048_577),
+      api_key: Rails.application.credentials.fetch(:unisender_api_key),
+      content_encoding: request.get_header("HTTP_CONTENT_ENCODING")
+    )
+    DeliveryEvent.transaction do
+      notification.users.each do |user|
+        user.events.each do |event|
+          value = [user.login, canonical(event.to_h)]
+          fingerprint = Digest::SHA256.hexdigest(JSON.generate(value))
+          DeliveryEvent.create_or_find_by!(fingerprint: fingerprint) do |record|
+            record.account = user.login
+            record.payload = event.to_h
+          end
+        end
+      end
+    end
+    head :ok
+  rescue Unisender::WebhookError
+    head :bad_request
+  end
+
+  private
+
+  def canonical(value)
+    case value
+    when Hash then value.sort.to_h.transform_values { |child| canonical(child) }
+    when Array then value.map { |child| canonical(child) }
+    else value
+    end
+  end
+end
+```
+
+GET acknowledges registration only. POST verifies the original body before parsing it into application records.
+Set a matching request-body limit in the web server. Return HTTP 200 only after the event transaction commits.
+The unique fingerprint suppresses repeated event content, even when a batch is regrouped or object keys change order.
+This is an application deduplication rule, not a provider event identifier. Retain the fingerprint for your full replay window.
+Serve this endpoint over HTTPS. Exclude webhook bodies from request logging and error-reporting attachments.
+
+Add the payload keys to `config/initializers/filter_parameter_logging.rb`:
+
+```ruby
+Rails.application.config.filter_parameters += [:auth, :api_key, :events_by_user]
+```
+
+Configure external error and HTTP logging tools separately; Rails parameter filters do not control those tools.
+
+## Process persisted events separately
+
+Add `app/jobs/process_delivery_events_job.rb`:
+
+<!-- file: app/jobs/process_delivery_events_job.rb -->
+```ruby
+class ProcessDeliveryEventsJob < ApplicationJob
+  def perform
+    DeliveryEvent.where(processed_at: nil).find_each do |event|
+      event.with_lock do
+        next if event.processed_at
+        apply_status(event)
+        event.update!(processed_at: Time.current)
+      end
+    end
+  end
+
+  private
+
+  def apply_status(event)
+    payload = event.payload
+    return unless payload["event_name"] == "email_status"
+    data = payload.fetch("event_data")
+    return unless data["email_id"]
+    delivery = EmailDelivery.create_or_find_by!(account: event.account, email_id: data.fetch("email_id").to_s)
+    observed = Time.find_zone!("UTC").parse(payload.fetch("event_time"))
+    delivery.with_lock do
+      if delivery.observed_at.nil? || observed > delivery.observed_at
+        delivery.update!(status: data.fetch("status"), observed_at: observed)
+      end
+    end
+  end
+end
+```
+
+Schedule this job periodically through your job backend. It also recovers events persisted before a process crash.
+Event processing and the processed marker commit together. Repeated processing does not repeat the state change.
+The timestamp guard prevents older notifications from replacing newer status.
+This example projects direct-email delivery, using IDs returned by `send_email.accepted_ids`.
+Campaign notifications use `campaign_id` and recipient email; add a separate projection when your application needs campaign delivery.
+Equal timestamps keep the first observed status. Define a domain-specific precedence if your application needs finer ordering.
+
+Receipt and processing are separate: the receiver persists, then the worker updates application state.
+Database failures produce a non-200 response and allow provider redelivery. Authentication failures never create event records.
+Signature details and provider limitations are in the [webhook guide](webhooks.md).
+
+## Test without an account
+
+Inject `Unisender::Testing::Transport` into `ImportProcessor` and queue `Fixtures.import_result` responses.
+Test complete acceptance, partial acceptance, transport failure, duplicate jobs, and restart from an in-flight marker.
+For the receiver, sign synthetic payloads with a fake key. Test invalid auth, duplicate delivery, reordered JSON keys, and older events.
+See [testing support](testing.md) for request assertions and [serialization](usage.md#responses-and-failures) for `only:` and `except:`.

data/docs/releases.md

@@ -9,11 +9,11 @@ Starting with 0.1.1, GitHub releases include the gem, an SPDX inventory of its p
 Download and verify a release in your terminal:
 
 ```sh
-gh release download v0.1.1 --repo svyatov/unisender-ruby --dir release
+gh release download v0.2.0 --repo svyatov/unisender-ruby --dir release
 cd release
-gh attestation verify unisender-ruby.gem --repo svyatov/unisender-ruby --signer-workflow svyatov/unisender-ruby/.github/workflows/release.yml --source-ref refs/tags/v0.1.1
-gh attestation verify sbom.spdx.json --repo svyatov/unisender-ruby --signer-workflow svyatov/unisender-ruby/.github/workflows/release.yml --source-ref refs/tags/v0.1.1
-gh attestation verify SHA256SUMS --repo svyatov/unisender-ruby --signer-workflow svyatov/unisender-ruby/.github/workflows/release.yml --source-ref refs/tags/v0.1.1
+gh attestation verify unisender-ruby.gem --repo svyatov/unisender-ruby --signer-workflow svyatov/unisender-ruby/.github/workflows/release.yml --source-ref refs/tags/v0.2.0
+gh attestation verify sbom.spdx.json --repo svyatov/unisender-ruby --signer-workflow svyatov/unisender-ruby/.github/workflows/release.yml --source-ref refs/tags/v0.2.0
+gh attestation verify SHA256SUMS --repo svyatov/unisender-ruby --signer-workflow svyatov/unisender-ruby/.github/workflows/release.yml --source-ref refs/tags/v0.2.0
 shasum -a 256 -c SHA256SUMS
 ```
 

data/docs/testing.md

@@ -0,0 +1,83 @@
+# Testing application integrations
+
+Load the optional fake transport explicitly. It has no runtime dependencies and never opens a socket.
+
+```ruby
+require "unisender/testing"
+
+transport = Unisender::Testing::Transport.new
+transport.enqueue(operation: "getLists", data: {
+  "result" => [{ "id" => 42, "title" => "News" }]
+})
+client = Unisender::Client.new(api_key: "test-key", transport:)
+
+raise "Unexpected lists" unless client.get_lists.map(&:id) == [42]
+raise "Missing format" unless transport.requests.first.form["format"] == "json"
+transport.verify!
+```
+
+Each request consumes one queued response. Missing responses and operation mismatches raise immediately.
+Call `verify!` at the end of a test to reject unused responses. Mismatch messages contain only recognized operation names.
+Use `enqueue(data:, http_status:, headers:)` for API errors, HTTP failures, warnings, and partial results.
+Use `enqueue_response` with an `HTTPResponse` for malformed JSON or an exception for transport failures.
+
+Request inspection omits payloads. `form` excludes the API key.
+Explicit `body`, `headers`, and `uri` access can expose credentials or contact data. Keep those values out of test failure output.
+Queued fixtures should use fake addresses and keys.
+
+## Fixtures and request expectations
+
+`Fixtures.list`, `Fixtures.import_result`, `Fixtures.task`, and `Fixtures.recipient` return result values without the outer `result` envelope.
+Required keywords describe the minimum usable fixture; optional keywords add failures, IDs, and download URLs.
+
+Add this expectation to an application test:
+
+```ruby
+transport.enqueue(
+  operation: "importContacts",
+  expected_form: { "field_names[0]" => "email", "data[0][0]" => "person@example.test" },
+  data: { "result" => Unisender::Testing::Fixtures.import_result(total: 1) }
+)
+```
+
+`expected_form:` checks selected encoded fields. `expected_json:` checks nested object subsets and positional array prefixes.
+Choose one per reply. Additional request fields are allowed; missing or different expected fields fail immediately.
+Error messages contain a redacted field path, without expected or actual payload values. API keys cannot be form expectations.
+Use exact request counts and `verify!` when order and extra requests matter.
+
+For Event Tracking, use `transport.requests.last.json` to inspect the decoded JSON payload with its `events` array.
+Like `body`, this reader contains contact data. Compare selected fields instead of printing the full payload.
+
+## Type checking in an application
+
+The gem packages RBS under `sig/`, including `sig/manifest.yaml`. With Steep installed in your application's development bundle, use this target in `Steepfile`:
+
+```ruby
+target :app do
+  check "app"
+  library "unisender-ruby"
+  library "net-http", "json", "uri", "openssl", "time", "ipaddr", "zlib", "stringio"
+end
+```
+
+Run `bundle exec steep check`. The gem includes its signatures; copying the library's source into your application is unnecessary.
+
+### Cursor setup
+
+Use [Steep](https://github.com/soutaro/steep) in your development bundle and the publisher's [Steep extension](https://marketplace.visualstudio.com/items?itemName=soutaro.steep-vscode).
+The extension repository is [soutaro/steep-vscode](https://github.com/soutaro/steep-vscode).
+If Cursor's registry does not list it, download the publisher's VSIX from Visual Studio Marketplace and use **Extensions: Install from VSIX**.
+
+1. Add `gem "steep", group: :development` to your application's Gemfile, then run `bundle install`.
+2. Add the `Steepfile` target above, changing `check "app"` to your source directory.
+3. Open the project folder in Cursor and run **Steep: Restart** from the command palette.
+4. Use **Trigger Suggest** for methods, **Show or Focus Hover** for keywords and return types, and the Problems panel for invalid calls.
+
+The extension launches `bin/steep langserver` when a binstub exists, otherwise `bundle exec steep langserver`.
+Ensure Cursor uses the same Ruby and bundle as your terminal. A version-manager shim must resolve Ruby in the project directory.
+On macOS, open the canonical folder path, such as `/private/tmp/project` rather than its `/tmp/project` symlink.
+Mismatched document paths can hide diagnostics even while the language server runs.
+
+Verified with Cursor 3.27.14, Steep extension 0.10.0, Steep 2.1.0, RBS 4.2.0, and Ruby 4.0.9.
+The consumer used an installed 0.2.0 gem outside this checkout.
+Observed in the editor: `get_*` completion, `CollectionResponse[List]` hover, required `title: String` keyword help, and rejection of `title: false`.