unisender-ruby 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d06d19534449d52a259839973e260a8cd7e11cbc50c8136bf963b47c06f86624
-  data.tar.gz: b0de90f56f2838c27f6a1b3eea28654d45209cc4e3446b6f401ce6f31f005d35
+  metadata.gz: f3678167b25f05feee7a6cbb24ead0d09fea765de2cbd815f092644c1ee62598
+  data.tar.gz: c0d66eec6a7c5ea4b93e162a7c4ebc62c9548585c6e4cf3cc5f49a50d345f0b5
 SHA512:
-  metadata.gz: 44c26c949db6f70ef169a21b2e2c523640cb3ead8d4b551aa6412dea828bf3bee6c874e162b3cfb3292534721d14b4d1ec114bfd58c4433a07e99f5e496dddbd
-  data.tar.gz: 5d554001273bfd9562c6968fcffe3f1b98c6706093dae5bcfee8f890ad08fb75486cafb418956776c976af581c41ddd8cb7f9f4c2ae29502e17624923c468816
+  metadata.gz: 8c15b5e69db9bb9584e75c52a1666ed99cf5cae211be9acf9b154943068e1f168803d332b2e907ec8ab4dccbec1ad7faceb3685a7006eaad4e97bb70b3ca5c8e
+  data.tar.gz: a634d99895b18c0df41f1e5b01f1943ca15f56e9921624be600c0be5b0eaf9b6e5e8745b7cb2d5e20c521127b679f8e0190a1fcf56dee239a788d96157e06a49

data/CHANGELOG.md

@@ -4,6 +4,95 @@ Unreleased collects changes for the next version. Dated sections list user-visib
 
 ## Unreleased
 
+## 0.2.0 - 2026-10-26
+
+- Parse diagnostic bracket fields without regex substitution while preserving index paths and redaction.
+
+- Add campaign lifecycle and durable import examples, a complete Rails integration, verified Cursor setup, and shorter task-oriented documentation.
+
+- Keep offline pagination validation aligned with execution and report indexed event and response-shape errors.
+- Mark acceptance as uncertain when responses omit inputs or return inconsistent counts; enforce false JSON expectations.
+
+- Add optional fixture builders and redacted subset assertions for queued form and JSON requests.
+
+- Add optional acceptance instrumentation with separate accepted, rejected, and unknown counts for sends, imports, and events.
+
+- Identify API requests with the gem and Ruby versions and document client ownership across variants, threads, and forks.
+
+- Add redacted error diagnostics, structural field paths, expected and actual types, and request context on malformed responses.
+
+- Add an independent optional Event Tracking rate limiter and validate message-default containers locally.
+
+- Add named mail headers, image-mode symbols, and explicit accepted, rejected, and unknown recipient views.
+
+- Accept SMS phone arrays and always return a typed receipt collection.
+
+- Give records class-sensitive value equality, forward object lookup, and avoid polling failed task handles.
+
+- Honor top-level `only` and `except` JSON filters and reject unsupported serialization options.
+
+- Validate named argument types locally and expose offline `Client#validate!` with shared normalization and encoding.
+
+- Bound direct imports to 501 inspected records and add optional byte limits to attachment reads.
+
+- Schedule Time inputs in explicit UTC with minute precision; reject conflicting timezones.
+
+- Document the accepted MD5 exception required by UniSender's webhook protocol.
+
+- Scan webhook JSON tokens without regular-expression backtracking and reject unterminated strings.
+- Escape backslashes as well as table separators in generated API type descriptions.
+
+- Preserve existing injected retry policies, rate limiters, and downloaders when execution scopes are enabled.
+- Add cooperative execution scopes and cancellation across retries, pacing, polling, and batch boundaries, with separate execution timing events and request IDs on request events.
+- Add opt-in summary retention and progress checkpoints for import and Event Tracking batches, preserving known source offsets for row diagnostics.
+- Add hook management and bounded JSON/gzip webhook authentication with typed notification readers.
+- Add fake-transport queue verification and JSON request access, durable export recovery examples, and opt-in staging contract probes.
+
+- Validate malformed contact fields and count filters locally, and preserve operation names and import column paths in validation errors.
+- Correct reference descriptions of legacy empty-result normalization.
+
+- Standardize input diagnostics, validate named flags and choices, and preserve wrapper failure context.
+- Normalize structured import cells and expose typed row warnings with known global indices.
+- Add scoped email/phone removal inputs and explicit contact-count filters.
+- Request detailed send acceptance by default; retain explicit legacy and omission options.
+
+- Accept blocks on page iterators and expose page checkpoint offsets.
+- Add Array-style collection access, Hash-style record lookup, and payload JSON serialization.
+- Add stable contact address readers, optional contact details, note metadata, and mutation result readers.
+- Return completed task handles without polling; expose task predicates and block-scoped client lifetime.
+
+- Separate development installation from published usage and link gem documentation to its version tag.
+- Generate API argument and result tables from RBS, with agreement checks for the Ruby interface.
+
+- Expose all documented import counters directly and normalize string-keyed default overrides.
+- Validate campaign encoding before creating a message.
+
+- Preserve accepted batches on source exceptions and task context on polling request failures.
+- Validate direct pagination controls and include named-result failures in instrumentation.
+- Reject special-use download addresses and complete Time signatures for iterators.
+
+- Add opt-in persistent HTTPS connections, lifecycle controls, and shared process-local request pacing.
+- Add binary attachment snapshots and a preflighted create-message/send-campaign workflow.
+- Add explicit, bounded export downloads without forwarding API credentials.
+
+- Add direct timeout and retry options, environment construction, immutable variants, and message defaults.
+- Add safe request instrumentation, structured error categories, recovery hints, and retry-safety checks.
+- Ship optional test transport support and application integration guides.
+- Expand typed contact, sender-domain, SMS, and campaign-statistics results.
+
+- Expose typed acceptance reports and global batch failure indices without replaying requests.
+- Split event batches by encoded bytes and count; preserve completed work when input enumeration fails.
+
+- Accept contact records, named subscription modes, and Ruby time inputs.
+- Add task handles with explicit polling, progress callbacks, and contextual timeout errors.
+
+- Execute batch commands immediately; provide explicit lazy batch and typed item iterators.
+- Add page navigation with resume offsets and immediate argument validation.
+
+- Return typed immutable records and enumerable collections from named operations.
+- Add direct field access, a boolean membership predicate, and singular message results.
+- Rename response HTTP metadata to `http_status`; preserve upstream JSON through `data`.
+
 ## 0.1.1 - 2026-10-25
 
 - Clarify installation, example destinations, contribution guidance, and maintainer policies.

data/CONTRIBUTING.md

@@ -39,9 +39,18 @@ Pre-commit hooks scan staged changes for secrets, apply and stage safe Ruby form
 
 ## Build and test the package
 
+API reference tables come from shipped RBS signatures and `docs/api_annotations.yml`.
+After changing either, regenerate the tables:
+
+```sh
+bundle exec ruby -r ./scripts/api_reference -e 'File.write("docs/api.md", APIReference.new(Dir.pwd).render)'
+```
+
+The regular test suite checks that generated tables match the public Ruby keywords.
+
 ```sh
 bundle exec rake build
-gem install --local ./pkg/unisender-ruby-0.1.1.gem
+ruby -e 'spec = Gem::Specification.load("unisender.gemspec"); system("gem", "install", "--local", "pkg/#{spec.file_name}") || abort("Install failed")'
 ```
 
 From outside the checkout, run `ruby -runisender -e 'puts Unisender::VERSION'`. For an isolated check, use a temporary `GEM_HOME` and `GEM_PATH`, and run the examples with a fake transport. The gem includes examples and RBS signatures; development dependencies are not runtime dependencies.

data/README.md

@@ -2,71 +2,50 @@
 
 A Ruby client for applications using the [UniSender marketing API](https://www.unisender.com/ru/support/category/api/).
 
-Ruby 3.3 or newer, no runtime gem dependencies. This client targets `api.unisender.com`, not UniSender Go.
-
-Explicit keyword methods cover contacts, lists, messages, campaigns, statistics, templates, fields, notes, and Event Tracking. Responses preserve upstream JSON, warnings, and HTTP metadata. See the [API reference](docs/api.md) for the operation index, argument types, and result shapes.
+- Ruby 3.3 or newer, with no runtime gem dependencies.
+- Contacts, lists, messages, campaigns, statistics, templates, fields, notes, and Event Tracking.
+- Typed immutable results, offline validation, and explicit pagination and batch recovery.
+- Targets `api.unisender.com` and Event Tracking, not UniSender Go.
 
 ## Install
 
-Install the gem:
-
-```sh
-gem install unisender-ruby
-```
+This guide covers version 0.2. See the [migration guide](docs/migration-0.2.md) when upgrading from 0.1.
 
-Save this read-only example as `quickstart.rb`. It uses the key in `UNISENDER_API_KEY`:
+Add the gem to your application's `Gemfile`:
 
-<!-- example: examples/quickstart.rb -->
 ```ruby
-require "unisender"
-
-client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
-client.get_lists.result.each { |list| puts list.fetch("title") }
-# Example output for a list named News: News
+gem "unisender-ruby", "~> 0.2.0", require: "unisender"
 ```
 
-Run `ruby quickstart.rb`. It prints one title per list, or nothing if the account has no lists. See [Make your first request](#make-your-first-request) for key setup.
-
-For a Bundler project, add the gem to your application's Gemfile:
-
-```ruby
-gem "unisender-ruby", "~> 0.1.1", require: "unisender"
-```
+Run `bundle install`.
+To build from a checkout, follow [build and installation](CONTRIBUTING.md#build-and-test-the-package).
+The package name is `unisender-ruby`; the Ruby load path is `unisender`.
 
-Then run `bundle install`. The package is named `unisender-ruby`; load it with `require "unisender"`.
+## Read your lists
 
-### Install from a checkout
+Get your key from [UniSender's API settings](https://www.unisender.com/ru/support/api/common/api-key/).
+Set `UNISENDER_API_KEY` through your shell or application's secret store.
+The library does not load `.env` files. Keep credentials out of source and logs.
 
-In your application's Gemfile, point to this repository:
+Save this as `quickstart.rb`:
 
+<!-- example: examples/quickstart.rb -->
 ```ruby
-gem "unisender-ruby", path: "../unisender-ruby", require: "unisender"
-```
-
-Adjust the path, then run `bundle install`. Alternatively, build and install the local package as described in [CONTRIBUTING.md](CONTRIBUTING.md#build-and-test-the-package).
-
-## Make your first request
-
-Get your key from [UniSender's API settings](https://www.unisender.com/ru/support/api/common/api-key/) and put it in the `UNISENDER_API_KEY` environment variable through your shell or application's secret store. Keep it out of source control and logs.
-
-For a local checkout, you can store `UNISENDER_API_KEY=your-key` in `.env`, which Git ignores. Ruby does not load this file automatically. Load your own `.env` into the current shell, then run the read-only connection check:
+require "unisender"
 
-```sh
-set -a
-. ./.env
-set +a
-bundle exec ruby examples/check_connection.rb
+client = Unisender::Client.new(api_key: ENV.fetch("UNISENDER_API_KEY"))
+client.get_lists.each { |list| puts list.title }
+# Example output for a list named News: News
 ```
 
-The check prints only the HTTP status and list count, including zero for an empty account. Failures exit with status 1. It does not print list names or IDs. The gem itself reads neither environment variables nor `.env`; application code passes the key explicitly.
-
-The `quickstart.rb` example above only reads lists. It does not create contacts or send messages. In a Bundler project, run it with `bundle exec ruby quickstart.rb`. A missing environment variable raises `KeyError` before any request. To try the client without an account or network access, run `bundle exec ruby examples/offline.rb` from this checkout.
+Run `bundle exec ruby quickstart.rb`. An empty account prints nothing.
+To try the client without credentials, run `bundle exec ruby examples/offline.rb` from the checkout.
 
 ## Subscribe a contact
 
-This operation changes your account and normally **sends a confirmation email**. Use an existing list ID from `get_lists`, and an address you control for a manual trial. Set `UNISENDER_LIST_ID` and `UNISENDER_CONTACT_EMAIL` before running it.
-
-Save the following example as `subscribe.rb`:
+This changes your account and normally **sends a confirmation email**.
+Set `UNISENDER_LIST_ID` to an existing list and `UNISENDER_CONTACT_EMAIL` to an address you control.
+Save this as `subscribe.rb`:
 
 <!-- example: examples/subscribe.rb -->
 ```ruby
@@ -75,86 +54,50 @@ 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
 ```
 
-The contact must confirm before receiving campaigns. Use `double_optin: 3` only when you already have consent; it adds the contact without sending the confirmation email. `overwrite: 0` preserves existing fields and tags, `1` replaces them and list membership, and `2` updates supplied fields. See the [upstream subscription rules](https://www.unisender.com/ru/support/api/contacts/subscribe/).
-
-## Complete workflows
-
-Each example is a standalone Ruby file. Its header lists required environment variables and account effects.
+Run `bundle exec ruby subscribe.rb`. The contact must confirm before receiving campaigns.
+Use `double_optin: :already_confirmed` only with consent already established.
+To check inputs without networking, call `client.validate!(:subscribe, list_ids: [123], email: "person@example.test")`.
 
-| Task | Example | Effect |
-| --- | --- | --- |
-| Read lists | [quickstart.rb](examples/quickstart.rb) | Read only |
-| Check credentials without printing account data | [check_connection.rb](examples/check_connection.rb) | Read only |
-| Test without credentials | [offline.rb](examples/offline.rb) | No network |
-| Subscribe a contact | [subscribe.rb](examples/subscribe.rb) | Changes contacts; sends confirmation |
-| Create and send a campaign | [campaign.rb](examples/campaign.rb) | Sends to the selected list |
-| Export contacts | [export.rb](examples/export.rb) | Starts and polls an export job |
-| Import batches with partial-failure handling | [import.rb](examples/import.rb) | Changes contacts |
-| Track events with partial-failure handling | [events.rb](examples/events.rb) | Records events; can trigger automation |
+## Handle a failure
 
-## Responses and failures
-
-Every operation returns `Unisender::Response`: `result`, `warnings`, `data` (the full JSON object), `status`, and `headers`. Values are deeply immutable. JSON keys are strings; numbers are not coerced. Read or copy the data explicitly when your application needs to change it.
-
-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.
-
-Use this error handler in your application's `request.rb`:
+Put error handling around calls in your application:
 
 ```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.status and error.response.headers.
-rescue Unisender::TransportError, Unisender::InvalidResponseError => error
-  warn error.message
-  # Check service availability before deciding whether to repeat the operation.
+rescue Unisender::Error => error
+  warn error.diagnostics.inspect
 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"),
-  transport: Unisender::Transport.new(open_timeout: 5, read_timeout: 60, write_timeout: 30),
-  retry_policy: Unisender::RetryPolicy.new(max_retries: 2, max_elapsed: 60)
-)
-```
-
-Those are the default transport timeouts in seconds. TLS certificates are verified, redirects are rejected, and calls do not share connections. **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 batch helpers return lazy Enumerators: **consume them to make requests**. Stopping enumeration prevents subsequent requests. `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](docs/api.md#convenience-operations) and [upstream rate limits](https://www.unisender.com/ru/support/api/common/api-limits/).
-
-## 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.
+`diagnostics` omits credentials and payloads. Local input errors raise `Unisender::ValidationError`, an `ArgumentError` subclass.
+A successful request can still reject recipients. Inspect `complete?`, `partial?`, and `uncertain?` on acceptance reports.
+Retries default to zero. Sends and mutations are never automatically retried.
 
-RBS signatures ship with the gem. `Response[Result]` describes a named operation's result; the low-level method keeps the general JSON type. Signatures describe documented shapes, not runtime schema validation. Unknown fields remain accessible through `response.data`. Consumer examples are checked with Steep alongside library code.
+## Find your task
 
-## Project information
+| Task | Guide or example |
+| --- | --- |
+| Choose an operation or find a keyword | [API reference](docs/api.md) |
+| Read results, configure clients, handle errors | [Usage guide](docs/usage.md) |
+| Create, inspect, test, and schedule a campaign | [Campaign lifecycle](examples/campaign_lifecycle.rb) |
+| Recover an import from durable checkpoints | [Import recovery](docs/import-recovery.md) |
+| Export and download contacts | [Export example](examples/export.rb) |
+| Record events | [Event example](examples/events.rb) |
+| Test an application or configure Cursor | [Testing and editor setup](docs/testing.md) |
+| Integrate Rails jobs and delivery webhooks | [Rails guide](docs/rails.md) |
+| Control pacing, cancellation, and resource ownership | [Execution guide](docs/execution.md) |
+| Upgrade from 0.1 | [Migration guide](docs/migration-0.2.md) |
 
-- [Contributing, local checks, and package verification](CONTRIBUTING.md)
-- [Changes and compatibility policy](CHANGELOG.md)
-- [Release verification](docs/releases.md)
-- [Source repository](https://github.com/svyatov/unisender-ruby) and [issue reports](https://github.com/svyatov/unisender-ruby/issues)
+## Help and project status
 
-This project is maintained by Leonid Svyatov. Use the public [issue tracker](https://github.com/svyatov/unisender-ruby/issues) for questions and defect reports. Report vulnerabilities privately through [SECURITY.md](SECURITY.md).
+Leonid Svyatov maintains this project. Use the public [issue tracker](https://github.com/svyatov/unisender-ruby/issues) for questions and defects.
+Report vulnerabilities privately through [SECURITY.md](SECURITY.md).
 
-Tests use fake credentials and deterministic responses. They do not establish compatibility with a live account. Released under the [MIT License](LICENSE.txt).
+See [contributing](CONTRIBUTING.md), [changes](CHANGELOG.md), [release verification](docs/releases.md), and the [MIT license](LICENSE.txt).
+Tests use fake credentials and deterministic responses. Live account compatibility requires separate [staging checks](docs/live-contracts.md).