unione 2.2.3 → 2.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -1,84 +1,58 @@
1
1
  # AGENTS.md
2
2
 
3
- UniOne Node.js SDK — client for the UniOne transactional email Web API (Web API 1.90).
3
+ UniOne Node.js 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.
4
4
 
5
- ## Working on this repository
6
-
7
- - **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-node-sdk).
8
- - **Build and check:**
9
-
10
- ```bash
11
- npm install
12
- npm pack --dry-run
13
- ```
14
-
15
- - **Source label.** Every request carries the query parameter `platform=node-sdk.2.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>,node-sdk.2.2.3`.
16
- - **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.
17
- - **Release.** The version (2.2.3 in package.json) and the tag `v2.2.3` come from the generator; README.md states the Web API version the release was generated from.
18
- - **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.
19
-
20
- ## Integrating UniOne with this SDK
5
+ ## Integrating UniOne
21
6
 
22
- Full quickstart: [README.md](README.md). Install:
23
-
24
- ```bash
25
- npm install unione
26
- ```
27
-
28
- Requirements: Node.js 18+.
29
-
30
- 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).
7
+ **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).
31
8
 
32
9
  | Framework | Package | Guide |
33
10
  |---|---|---|
34
11
  | Express | `unione-express` | [AGENTS.md](https://github.com/unione-repo/unione-express/blob/HEAD/AGENTS.md) |
35
12
  | NestJS | `unione-nestjs` | [AGENTS.md](https://github.com/unione-repo/unione-nestjs/blob/HEAD/AGENTS.md) |
36
13
 
37
- Rules that generated code must follow:
14
+ ### Install
38
15
 
39
- - Server-side only. Read the API key from `UNIONE_API_KEY`; never put it in browser or mobile code, never commit it.
40
- - 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.
41
- - 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.
42
- - 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`.
43
- - 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`.
44
- - 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.
45
- - Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
46
- - 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).
16
+ ```bash
17
+ npm install unione
18
+ ```
47
19
 
48
- ### Send an email
20
+ Requirements: Node.js 18+. The API key goes to `UNIONE_API_KEY`.
49
21
 
50
- The client reads the API key from `UNIONE_API_KEY`:
22
+ ### Send an email
51
23
 
52
24
  ```javascript
53
25
  import { UniOneClient } from "unione";
54
- import { EmailSendRequest, MessageObject, MessageObjectRecipientsItem } from "unione/api/email";
55
- import { BodyObject } from "unione/common";
26
+ import { MessageObjectRecipientsItem as Recipient } from "unione/api/email";
56
27
 
57
28
  const client = new UniOneClient(process.env.UNIONE_API_KEY);
58
29
 
59
- const response = await client.email.send(new EmailSendRequest({
60
- message: new MessageObject({
61
- recipients: [
62
- new MessageObjectRecipientsItem({
63
- email: "user@example.com",
64
- substitutions: {
65
- "CustomerId": "12452",
66
- "to_name": "John Smith",
67
- },
68
- }),
69
- ],
70
- body: new BodyObject({
71
- html: "<b>Hello, {{to_name}}</b>",
72
- plaintext: "Hello, {{to_name}}",
73
- }),
74
- subject: "UniOne test email ",
75
- fromEmail: "email@example.com",
76
- fromName: "John Smith",
77
- }),
78
- }));
79
- console.log(response.jobId);
30
+ const { jobId } = await client.email.send({
31
+ message: {
32
+ recipients: [Recipient.fromAddress("Alex <alex@example.com>")],
33
+ from_email: "shop@example.com",
34
+ from_name: "Shop",
35
+ subject: "Your order",
36
+ body: { html: "<p>Hello, {{to_name}}! Your order has shipped.</p>" },
37
+ },
38
+ });
39
+ console.log(jobId);
80
40
  ```
81
41
 
42
+ Personalization, attachments, CC/BCC, scheduling, safe retries, error handling, the webhook handler and the sandbox flow: the recipes of [README.md](README.md#recipes).
43
+
44
+ ### Rules for generated code
45
+
46
+ - Server-side only. Read the API key from `UNIONE_API_KEY`; never put it in browser or mobile code, never commit it.
47
+ - 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.
48
+ - 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.
49
+ - 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.
50
+ - 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`.
51
+ - 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`.
52
+ - 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.
53
+ - Keep the default unsubscribe and tracking behaviour; changes go through UniOne support.
54
+ - 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).
55
+
82
56
  ### Errors
83
57
 
84
58
  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.
@@ -101,3 +75,18 @@ try {
101
75
  - 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)
102
76
  - [API reference](https://docs.unione.io/en/web-api-ref)
103
77
  - [Full API reference for LLMs](https://docs.unione.io/llms-full.txt)
78
+
79
+ ## Working on this repository
80
+
81
+ - **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-node-sdk).
82
+ - **Build and check:**
83
+
84
+ ```bash
85
+ npm install
86
+ npm pack --dry-run
87
+ ```
88
+
89
+ - **Source label.** Every request carries the query parameter `platform=node-sdk.2.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>,node-sdk.2.2.4`.
90
+ - **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.
91
+ - **Release.** The version (2.2.4 in package.json) and the tag `v2.2.4` come from the generator; README.md states the Web API version the release was generated from.
92
+ - **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "unione",
3
- "version": "2.2.3",
3
+ "version": "2.2.4",
4
4
  "description": "UniOne Web API client library for Node.js",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
@@ -34,7 +34,7 @@ export function extraFields(data, names) {
34
34
  }
35
35
 
36
36
  /** The SDK and its version in the "platform" query parameter of every request. */
37
- export const PLATFORM = "node-sdk.2.2.3";
37
+ export const PLATFORM = "node-sdk.2.2.4";
38
38
 
39
39
  /**
40
40
  * Sets a header, replacing one of the same name in another case.
@@ -36,7 +36,7 @@ export class Configuration {
36
36
  * that uses the SDK and its version (e.g. "express.1.0.0"), sent in the "platform" query parameter before the SDK
37
37
  * one (PLATFORM); headers: extra headers of every request; fetch: a fetch-compatible function, default: globalThis.fetch.
38
38
  */
39
- constructor(apiKey, { baseUrl = DEFAULT_BASE_URL, timeout = 30000, userAgent = "unione-node-sdk/2.2.3", platform, headers = {}, fetch } = {}) {
39
+ constructor(apiKey, { baseUrl = DEFAULT_BASE_URL, timeout = 30000, userAgent = "unione-node-sdk/2.2.4", platform, headers = {}, fetch } = {}) {
40
40
  this.apiKey = apiKey;
41
41
  this.baseUrl = baseUrl.replace(/\/+$/, "");
42
42
  this.timeout = timeout;