unisender-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5816a7b213b4919d38f81de3568187d4dd1a2f345413b529f3961c2fad33f187
-  data.tar.gz: 0c0dcea4ad0cb5f1e4a2f5d2a502562ff68d3edebe1fdc04c3c7e95675fc4a9f
+  metadata.gz: f3678167b25f05feee7a6cbb24ead0d09fea765de2cbd815f092644c1ee62598
+  data.tar.gz: c0d66eec6a7c5ea4b93e162a7c4ebc62c9548585c6e4cf3cc5f49a50d345f0b5
 SHA512:
-  metadata.gz: 2d6e970aa069fb618f59335fc935ec897f4513af963ab60728c8379072a88bdf06eb08103e7b67a942d283e3e0b308c3a546aa91e26d0a26ee8c1089a158789b
-  data.tar.gz: '09e933af3af43cd61bb7c03a9a8c852813b24f22c766e4d1446008c1bddadb4c2d24d964a919272f489ab78c78ea73e40f5e598bb24570164b3f57b342f1b474'
+  metadata.gz: 8c15b5e69db9bb9584e75c52a1666ed99cf5cae211be9acf9b154943068e1f168803d332b2e907ec8ab4dccbec1ad7faceb3685a7006eaad4e97bb70b3ca5c8e
+  data.tar.gz: a634d99895b18c0df41f1e5b01f1943ca15f56e9921624be600c0be5b0eaf9b6e5e8745b7cb2d5e20c521127b679f8e0190a1fcf56dee239a788d96157e06a49

data/CHANGELOG.md

@@ -1,7 +1,104 @@
 # Changelog
 
+Unreleased collects changes for the next version. Dated sections list user-visible changes, newest first. GitHub release notes reproduce the corresponding section.
+
 ## 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.
+- Include security, conduct, and release verification documents in the gem.
+- Publish signed releases through an approval-gated workflow with an exact-file SPDX inventory and verifiable release assets.
+
 ## 0.1.0 - 2026-10-25
 
 - Publish as `unisender-ruby`; load with `require "unisender"` and use the `Unisender` namespace.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,90 @@
+
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, email [Leonid Svyatov](mailto:leonid@svyatov.com). Leonid moderates this community and will respond within seven days.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) Warning
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) Temporarily Limited Activities
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) Temporary Suspension
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) Permanent Ban
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).

data/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-This repository is private. Collaborators can use the [issue tracker](https://github.com/svyatov/unisender-ruby/issues). Include the Ruby and gem versions, a minimal example with fake values, expected behavior, and a redacted exception message. Do not post API keys, contact data, export links, or raw request/response bodies.
+Contributions and questions are welcome through the [issue tracker](https://github.com/svyatov/unisender-ruby/issues). Include the Ruby and gem versions, a minimal example with fake values, expected behavior, and a redacted exception message. Do not post API keys, contact data, export links, or raw request/response bodies.
 
 ## Set up
 
@@ -13,10 +13,16 @@ bundle exec rake check
 
 `bin/setup` installs development dependencies and Lefthook hooks. The complete check runs offline tests, RuboCop, RBS validation, Steep for the library and consumer examples, the dependency vulnerability audit, and the gem build. The audit updates its advisory database and needs network access.
 
+CI runs `bundle exec rake ci` for lint, tests, types, and the build. Dependency review blocks newly introduced vulnerabilities. A separate advisory job reports vulnerabilities across the lockfile without blocking unrelated changes.
+
 ## Make a change
 
 Use a branch such as `fix/error-context` or `feat/new-operation`. Read the official UniSender method documentation before changing a wire contract. Add a regression test with a deterministic transport, keep signatures in `sig/` synchronized, update the relevant docs, and add an entry under Unreleased in [CHANGELOG.md](CHANGELOG.md).
 
+Follow the repository requirements in [AGENTS.md](AGENTS.md) and the [code of conduct](CODE_OF_CONDUCT.md). New functionality must include tests.
+
+Fork the repository and create your branch from `main`. Push the branch to your fork, then open a pull request against `svyatov/unisender-ruby:main`. Describe the affected public interface and include the evidence needed to assess the change. Keep unrelated changes in separate pull requests. Maintainers use squash merges.
+
 | Command | Purpose |
 | --- | --- |
 | `bundle exec rake test` | Minitest with 100% line and branch coverage across `lib/` and `scripts/` |
@@ -33,11 +39,26 @@ 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.0.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.
 
 Routine verification must not call a live account, send messages, or change contacts. Live checks require explicit authorization and a designated test account. Publishing and releases are separate maintainer actions.
+
+## Maintainer decisions
+
+Leonid Svyatov is the sole maintainer and decides which changes merge and which versions are released. No successor is arranged if he stops maintaining the project.
+
+Report vulnerabilities privately using [SECURITY.md](SECURITY.md).

data/README.md

@@ -1,59 +1,51 @@
 # Unisender
 
-A Ruby client for 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.
+A Ruby client for applications using the [UniSender marketing API](https://www.unisender.com/ru/support/category/api/).
 
-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
 
-Add the gem to your application's Gemfile:
+This guide covers version 0.2. See the [migration guide](docs/migration-0.2.md) when upgrading from 0.1.
 
-```ruby
-gem "unisender-ruby", "~> 0.1.0", require: "unisender"
-```
-
-Then run `bundle install`. To install it directly, run `gem install unisender-ruby`. The package is named `unisender-ruby`; load it with `require "unisender"`.
-
-### Install from a checkout
-
-In your application's Gemfile, point to this repository:
+Add the gem to your application's `Gemfile`:
 
 ```ruby
-gem "unisender-ruby", path: "../unisender-ruby", require: "unisender"
+gem "unisender-ruby", "~> 0.2.0", 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
+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`.
 
-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.
+## Read your lists
 
-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:
+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.
 
-```sh
-set -a
-. ./.env
-set +a
-bundle exec ruby examples/check_connection.rb
-```
-
-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.
-
-This example only reads your lists. It does not create contacts or send messages:
+Save this as `quickstart.rb`:
 
 <!-- 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") }
+client.get_lists.each { |list| puts list.title }
+# Example output for a list named News: News
 ```
 
-Save it as `quickstart.rb` and run `bundle exec ruby quickstart.rb`. It prints one title per list, or nothing if the account has no lists. 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.
+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
@@ -62,79 +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.
-
-| 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 |
+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")`.
 
-## Responses and failures
+## Handle a failure
 
-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.
+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
-
-```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
+`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.
 
-`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.
+## Find your task
 
-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.
+| 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) |
 
-## Project information
+## Help and project status
 
-- [Contributing, local checks, and package verification](CONTRIBUTING.md)
-- [Changes and compatibility policy](CHANGELOG.md)
-- [Source repository](https://github.com/svyatov/unisender-ruby) and [issue reports](https://github.com/svyatov/unisender-ruby/issues)
+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).
 
-The repository is currently private; its GitHub links require access. 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).

data/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+## Supported versions
+
+Security fixes target the latest published release. Upgrade to that release before reporting a problem when possible.
+
+## Report a vulnerability
+
+Email [Leonid Svyatov](mailto:leonid@svyatov.com) privately. Expect an initial response within seven days.
+
+Include the affected gem and Ruby versions, the security impact, and a minimal reproduction using fake credentials and contact data. Do not include live API keys, recipient data, or account exports. Do not disclose the vulnerability in a public issue before a fix or coordinated disclosure date is agreed.
+
+The maintainer will assess the report and coordinate a fix and disclosure with you.