unisender-ruby 0.1.0

checksums.yaml

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

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-10-25
+
+- Publish as `unisender-ruby`; load with `require "unisender"` and use the `Unisender` namespace.
+- Initial release of the UniSender marketing API client for Ruby 3.3 and newer, with no runtime gem dependencies.
+- Add contacts, lists, messages, campaigns, statistics, templates, fields, notes, and Event Tracking operations.
+- Add immutable responses, distinct API and transport errors, opt-in read-only retries, pagination, polling, and batch helpers.
+- Document local `.env` loading and add a read-only connection check that prints no account data.
+- Ignore local `.env` files and clarify the required UTC timestamp format for campaign reads.
+- Document checkout installation, read-only onboarding, complete task examples, API argument types, and response contracts.
+- Add typed response contracts and consumer example checks.
+- Accept the documented top-level success objects from `sendTestEmail` and `updateField`.
+- Include known operation names, HTTP statuses, and documented API error codes in safe exception messages.
+- Add project metadata, contribution guidance, and standard Conventional Commit types.
+
+## Compatibility policy
+
+Before 1.0, a minor release may change public behavior with migration notes here. Patch releases preserve the documented public interface. After 1.0, releases follow semantic versioning.
+
+The public interface consists of the documented `Unisender::Client`, transport injection contract, responses, errors, retry policy, helpers, and their RBS signatures. Internal modules are implementation details. JSON keys and values preserve upstream representations, including unknown fields; callers must allow for service-side additions. Changes to supported Ruby versions are announced here.
+
+Local fake-response tests do not prove live-account compatibility. Upstream API changes can require a library update even when its Ruby interface is unchanged.

data/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# 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.
+
+## Set up
+
+Use Ruby 3.3 or newer and Bundler. CI checks Ruby 3.3, 3.4, and 4.0. Install [Betterleaks](https://github.com/betterleaks/betterleaks) using its upstream installation instructions and ensure `betterleaks` is on `PATH`. Then run:
+
+```sh
+bin/setup
+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.
+
+## 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).
+
+| Command | Purpose |
+| --- | --- |
+| `bundle exec rake test` | Minitest with 100% line and branch coverage across `lib/` and `scripts/` |
+| `bundle exec rake lint` | Ruby style and packaging checks |
+| `bundle exec rake format` | Safe RuboCop corrections |
+| `bundle exec rake typecheck` | RBS validation, Steep, and 100% library typed-call coverage |
+| `bundle exec rake audit` | Dependency vulnerability audit |
+| `bundle exec rake build` | Build the gem in `pkg/` |
+| `git diff --check` | Whitespace checks |
+
+Coverage results are not merged with previous runs. Inspect `coverage/index.html` for missing lines or branches. A focused test run can fail the global coverage threshold; run the complete suite before submitting. Typed-call coverage measures the library; the consumer target separately checks that documented workflows type-check.
+
+Pre-commit hooks scan staged changes for secrets, apply and stage safe Ruby formatting fixes, and check whitespace. Commit messages follow Conventional Commits, including `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `perf:`, `build:`, `ci:`, `chore:`, and `revert:`, with optional scope and `!`. Pre-push runs the complete suite. Put local overrides in ignored `lefthook-local.yml`.
+
+## Build and test the package
+
+```sh
+bundle exec rake build
+gem install --local ./pkg/unisender-ruby-0.1.0.gem
+```
+
+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.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonid Svyatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# 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.
+
+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.
+
+## Install
+
+Add the gem to your application's Gemfile:
+
+```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:
+
+```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:
+
+```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:
+
+<!-- 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") }
+```
+
+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.
+
+## 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.
+
+<!-- example: examples/subscribe.rb -->
+```ruby
+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") }
+)
+puts response.result.fetch("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 |
+
+## 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.
+
+```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.
+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
+
+`client.request("getLists", params: {})` accepts exact upstream names. It handles authentication, encoding, and failures, but does not perform operation-specific conversions. Comma-separated fields must already be strings; nested arrays and hashes become bracketed form fields. Credentials and JSON format cannot be overridden.
+
+RBS signatures ship with the gem. `Response[Result]` describes a named operation's result; the low-level method keeps the general JSON type. Signatures describe documented shapes, not runtime schema validation. Unknown fields remain accessible through `response.data`. Consumer examples are checked with Steep alongside library code.
+
+## Project information
+
+- [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)
+
+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).