unione 1.2.3 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 905c25d5be2c9eb7f499e528962a173bd5852d40ed4239d07d9484d830227900
-  data.tar.gz: 2b0bc8aa4a2149a3e663ed7da251174ceeb180671e3f90ee932814ad791cbfc9
+  metadata.gz: 1d86bd592e33bc40ed8d53bcff63702b395ef838be66048185f0bb7f2aa81dc9
+  data.tar.gz: 1c07d213b80dd4b7d10d773d0467d9134c5e1cf741cdb96ee8b2f3d531cc3ff1
 SHA512:
-  metadata.gz: a0916665cc508953defe333e3517a0b72b0000a6dde8ffce70753e1cf01a5b9772fd78a26a118c188481f55c41bc40601345c86574399afab16a296e96323c06
-  data.tar.gz: 92a7e623a9c261c4577cbeb3cbce612dfa21742bdad0a48c30628f844f2f4d0fb5bacf0755d9eaec37d5c6588da303398b60cfb07c412276416e04a32d20f00f
+  metadata.gz: f7c1bbac87f18795fc82876ca75fc5385e81cdfb9881bc1d6e095e5c0284474e4334d74da72c8382390da3ad0b01c133545653ccadf8397ab86bc03f9bd45ad7
+  data.tar.gz: 7156691b8ece43855f73ab61d7273c854c84748b08a931b7eae75b1d01cb3fa2cccfd20f00946b7f58fd835cb8ae0431261e6a796050e2f87593ae1b7137c616

data/AGENTS.md

@@ -1,83 +1,59 @@
 # AGENTS.md
 
-UniOne Ruby SDK — client for the UniOne transactional email Web API (Web API 1.90).
+UniOne Ruby SDK — client for the UniOne transactional email Web API (Web API 1.90). How to integrate UniOne into an application comes first; the last section is about changing this package.
 
-## Working on this repository
-
-- **Generated code.** The whole package is generated by the UniOne team from the UniOne Web API OpenAPI spec (Web API 1.90): sources, docs, README.md and this file. Do not hand-edit it: the next release replaces the content of this repository. Report problems and requests in the issues of this repository (https://github.com/unione-repo/unione-ruby-sdk).
-- **Build and check:**
-
-  ```bash
-  gem build *.gemspec
-  ```
+## Integrating UniOne
 
-- **Source label.** Every request carries the query parameter `platform=ruby-sdk.1.2.3`, added in one place, the shared request client (`ApiClient`); a package built on this SDK puts its own label in front: `<package>.<version>,ruby-sdk.1.2.3`.
-- **Tests.** Before a release the generator builds and lints the package and runs every example of docs/ and of this file against a mock of the API: no real API key, no real sends.
-- **Release.** The version (1.2.3 in the gemspec) and the tag `v1.2.3` come from the generator; README.md states the Web API version the release was generated from.
-- **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.
+**On one of these frameworks, install its package instead of this SDK:** it brings the SDK and plugs it into the framework (configuration, client in the container, mailer, webhooks).
 
-## Integrating UniOne with this SDK
+| Framework | Package | Guide |
+|---|---|---|
+| Ruby on Rails | `unione-rails` | [AGENTS.md](https://github.com/unione-repo/unione-rails/blob/HEAD/AGENTS.md) |
 
-Full quickstart: [README.md](README.md). Install:
+### Install
 
 ```bash
 gem install unione
 ```
 
-Requirements: Ruby 2.7+.
-
-If the project is built on one of these frameworks, install its package instead: it brings this SDK and plugs it into the framework (configuration, client in the container, mailer, webhooks).
-
-| Framework | Package | Guide |
-|---|---|---|
-| Ruby on Rails | `unione-rails` | [AGENTS.md](https://github.com/unione-repo/unione-rails/blob/HEAD/AGENTS.md) |
-
-Rules that generated code must follow:
-
-- Server-side only. Read the API key from `UNIONE_API_KEY`; never put it in browser or mobile code, never commit it.
-- Base URL `https://api.unione.io/en/transactional/api/v1` (an account registered on another host uses that one: `eu1.unione.io`, `us1.unione.io`); every method is POST with a JSON body; auth header `X-API-KEY`. The SDK does all of it.
-- First email without DNS: `domain/get-sandbox-domain` → `confirmed-email/create` (the user clicks the link within 48 hours) → `email/send` from `noreply@<sandbox-domain>` to the confirmed address. Account API key only; up to 10 confirmed addresses, 100 emails a day; the domain expires after 31 days.
-- Never ship a sandbox domain as the production sender (it is not in `domain/list`); read `from_email` from config. Production needs a verified domain: `domain/get-dns-records` → DNS records → `domain/validate-verification-record`, `domain/validate-dkim` → `domain/list`.
-- Set `message.idempotence_key` on retryable sends; retry network errors, `429` and `5xx` with backoff, not other errors unchanged. Up to 500 recipients and 10 MB per request with the attachments in base64 (a third larger than the files); always `body.html` or `body.plaintext`.
-- Delivery events via webhook (`webhook/set`) with a fast, idempotent HTTPS handler, not polling; check the `auth` field of every notification: the MD5 of the request body with the `auth` value replaced by the API key.
-- Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
-- Do not invent methods or fields. Check [docs/](docs/) of this package, the [API reference](https://docs.unione.io/en/web-api-ref) or [llms.txt](https://docs.unione.io/llms.txt).
+Requirements: Ruby 2.7+. The API key goes to `UNIONE_API_KEY`.
 
 ### Send an email
 
-The client reads the API key from `UNIONE_API_KEY`:
-
 ```ruby
 require 'unione'
 
-Common = UniOne::Common::Model
+Body = UniOne::Common::Model::BodyObject
 Email = UniOne::Api::Email::Model
+Recipient = UniOne::Api::Email::Model::MessageObjectRecipientsItem
 
 client = UniOne.client(ENV.fetch('UNIONE_API_KEY'))
 
-response = client.email.send_email(Email::EmailSendRequest.new(
-  message: Email::MessageObject.new(
-    recipients: [
-      Email::MessageObjectRecipientsItem.new(
-        email: 'user@example.com',
-        substitutions: {
-          'CustomerId' => '12452',
-          'to_name' => 'John Smith',
-        }
-      )
-    ],
-    body: Common::BodyObject.new(
-      html: '<b>Hello, {{to_name}}</b>',
-      plaintext: 'Hello, {{to_name}}'
-    ),
-    subject: 'UniOne test email ',
-    from_email: 'email@example.com',
-    from_name: 'John Smith'
-  )
-))
-p response.job_id
+message = Email::MessageObject.new(
+  recipients: [Recipient.from_address('Alex <alex@example.com>')],
+  body: Body.html('<p>Hello, {{to_name}}! Your order has shipped.</p>'),
+  subject: 'Your order',
+  from_email: 'shop@example.com',
+  from_name: 'Shop'
+)
+response = client.email.send_email(Email::EmailSendRequest.new(message: message))
+puts response.job_id
 ```
 
+Personalization, attachments, CC/BCC, scheduling, safe retries, error handling, the webhook handler and the sandbox flow: the recipes of [README.md](README.md#recipes).
+
+### Rules for generated code
+
+- Server-side only. Read the API key from `UNIONE_API_KEY`; never put it in browser or mobile code, never commit it.
+- Build the recipients and the body with the short forms of the SDK (the recipient from `"Name <email>"`, the name goes to `to_name`; per-recipient metadata; the HTML / text body), as in "Send an email" and the README recipes, not with hand-built nested objects.
+- Base URL `https://api.unione.io/en/transactional/api/v1` (an account registered on another host uses that one: `eu1.unione.io`, `us1.unione.io`); every method is POST with a JSON body; auth header `X-API-KEY`. The SDK does all of it.
+- First email without DNS: `domain/get-sandbox-domain` → `confirmed-email/create` (the user clicks the link within 48 hours) → `email/send` from `noreply@<sandbox-domain>` to the confirmed address. Account API key only; up to 10 confirmed addresses, 100 emails a day. The domain is deleted 31 days after it was created: the next `domain/get-sandbox-domain` call creates a new one with another name, so read the name from the response, never hardcode it.
+- Never ship a sandbox domain as the production sender (it is not in `domain/list`); read `from_email` from config. Production needs a verified domain: `domain/get-dns-records` → DNS records (verification TXT as is, DKIM TXT `v=DKIM1; k=rsa; p=<dkim>` on `<selector>._domainkey`, CNAME `_dmarc` → the `dmarc` field; SPF `include:spf.unione.io` is not in the response) → `domain/validate-verification-record`, `domain/validate-dkim` → `domain/list`.
+- Set `message.idempotence_key` on retryable sends; retry network errors, `429` and `5xx` with backoff, not other errors unchanged. Up to 500 recipients and 10 MB per request with the attachments in base64 (a third larger than the files); always `body.html` or `body.plaintext`.
+- Delivery events via webhook (`webhook/set`), not polling. Check the `auth` field of every notification (MD5 of the raw request body with the `auth` value replaced by the API key) and answer 401 to a wrong one. Answer 200 within 3 seconds and process the events from a queue, otherwise the request is repeated every 10 minutes for 24 hours; take at least 5 parallel requests of up to 100 events each; deduplicate.
+- Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
+- Do not invent methods or fields. Check [docs/](docs/) of this package, the [API reference](https://docs.unione.io/en/web-api-ref) or [llms.txt](https://docs.unione.io/llms.txt).
+
 ### Errors
 
 Every method throws `ApiError` when the request fails: the HTTP status (0 for a network error or a timeout), the [API error code](https://docs.unione.io/en/web-api-ref#api-errors) and the message.
@@ -97,3 +73,17 @@ end
 - Methods and models of every section: [Email](docs/Email.md), [EmailValidation](docs/EmailValidation.md), [ConfirmedEmail](docs/ConfirmedEmail.md), [Template](docs/Template.md), [Webhook](docs/Webhook.md), [Suppression](docs/Suppression.md), [Domain](docs/Domain.md), [EventDump](docs/EventDump.md), [Tag](docs/Tag.md), [Project](docs/Project.md), [System](docs/System.md), [Obsolete](docs/Obsolete.md)
 - [API reference](https://docs.unione.io/en/web-api-ref)
 - [Full API reference for LLMs](https://docs.unione.io/llms-full.txt)
+
+## Working on this repository
+
+- **Generated code.** The whole package is generated by the UniOne team from the UniOne Web API OpenAPI spec (Web API 1.90): sources, docs, README.md and this file. Do not hand-edit it: the next release replaces the content of this repository. Report problems and requests in the issues of this repository (https://github.com/unione-repo/unione-ruby-sdk).
+- **Build and check:**
+
+  ```bash
+  gem build *.gemspec
+  ```
+
+- **Source label.** Every request carries the query parameter `platform=ruby-sdk.1.2.4`, added in one place, the shared request client (`ApiClient`); a package built on this SDK puts its own label in front: `<package>.<version>,ruby-sdk.1.2.4`.
+- **Tests.** Before a release the generator builds and lints the package and runs every example of docs/ and of this file against a mock of the API: no real API key, no real sends.
+- **Release.** The version (1.2.4 in the gemspec) and the tag `v1.2.4` come from the generator; README.md states the Web API version the release was generated from.
+- **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.

data/lib/unione/client/api_client.rb

@@ -7,7 +7,7 @@ require 'uri'
 module UniOne
   module Client
     # The SDK and its version in the "platform" query parameter of every request.
-    PLATFORM = 'ruby-sdk.1.2.3'
+    PLATFORM = 'ruby-sdk.1.2.4'
 
     # Default transport (HTTP layer of ApiClient): Net::HTTP of the standard library.
     #

data/lib/unione/client/configuration.rb

@@ -36,7 +36,7 @@ module UniOne
       #   default ones of the same name
       attr_accessor :headers
 
-      def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, user_agent: 'unione-ruby-sdk/1.2.3', platform: nil, headers: {})
+      def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, user_agent: 'unione-ruby-sdk/1.2.4', platform: nil, headers: {})
         @api_key = api_key
         @base_url = base_url.sub(%r{/+\z}, '')
         @timeout = timeout

data/lib/unione/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UniOne
-  VERSION = '1.2.3'
+  VERSION = '1.2.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: unione
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.2.4
 platform: ruby
 authors:
 - UniOne