unione 1.2.3 → 2.2.3
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 +10 -3
- package/README.md +3 -3
- package/package.json +2 -2
- package/src/client/ApiClient.js +12 -52
- package/src/client/ApiError.js +1 -5
- package/src/client/Configuration.d.ts +1 -1
- package/src/client/Configuration.js +3 -3
package/AGENTS.md
CHANGED
|
@@ -12,9 +12,9 @@ UniOne Node.js SDK — client for the UniOne transactional email Web API (Web AP
|
|
|
12
12
|
npm pack --dry-run
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
- **Source label.** Every request carries the query parameter `platform=node-sdk.
|
|
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
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 (
|
|
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
18
|
- **Secrets.** Never commit API keys; the examples read `UNIONE_API_KEY` from the environment.
|
|
19
19
|
|
|
20
20
|
## Integrating UniOne with this SDK
|
|
@@ -25,7 +25,14 @@ Full quickstart: [README.md](README.md). Install:
|
|
|
25
25
|
npm install unione
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
Requirements: Node.js
|
|
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).
|
|
31
|
+
|
|
32
|
+
| Framework | Package | Guide |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| Express | `unione-express` | [AGENTS.md](https://github.com/unione-repo/unione-express/blob/HEAD/AGENTS.md) |
|
|
35
|
+
| NestJS | `unione-nestjs` | [AGENTS.md](https://github.com/unione-repo/unione-nestjs/blob/HEAD/AGENTS.md) |
|
|
29
36
|
|
|
30
37
|
Rules that generated code must follow:
|
|
31
38
|
|
package/README.md
CHANGED
|
@@ -14,9 +14,9 @@ Official Node.js library for the [UniOne](https://unione.io) transactional email
|
|
|
14
14
|
npm install unione
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
Requirements: Node.js
|
|
17
|
+
Requirements: Node.js 18+. No third-party dependencies.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
For Node.js 14 use the 1.x line (branch `1.x`), the same API.
|
|
20
20
|
|
|
21
21
|
Get an API key in the [control panel](https://cp.unione.io/en/settings/security/api) and keep it in the environment, never in code:
|
|
22
22
|
|
|
@@ -316,7 +316,7 @@ Every method raises `ApiError` when the API returns an error; it carries the [AP
|
|
|
316
316
|
|
|
317
317
|
### Custom HTTP client and headers
|
|
318
318
|
|
|
319
|
-
`headers` adds headers to every request; `fetch` replaces the function the requests go through (default:
|
|
319
|
+
`headers` adds headers to every request; `fetch` replaces the function the requests go through (default: `globalThis.fetch`): undici, node-fetch or a wrapper that adds retries, logging or a proxy. Network errors, timeouts and errors of reading the response raise `ApiError` (the original error is its `cause`).
|
|
320
320
|
|
|
321
321
|
```javascript
|
|
322
322
|
import { UniOneClient, ApiError } from "unione";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "unione",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.2.3",
|
|
4
4
|
"description": "UniOne Web API client library for Node.js",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./src/index.js",
|
|
@@ -74,7 +74,7 @@
|
|
|
74
74
|
"AGENTS.md"
|
|
75
75
|
],
|
|
76
76
|
"engines": {
|
|
77
|
-
"node": ">=
|
|
77
|
+
"node": ">=18"
|
|
78
78
|
},
|
|
79
79
|
"keywords": [
|
|
80
80
|
"unione",
|
package/src/client/ApiClient.js
CHANGED
|
@@ -1,5 +1,3 @@
|
|
|
1
|
-
import http from "http";
|
|
2
|
-
import https from "https";
|
|
3
1
|
import { ApiError } from "./ApiError.js";
|
|
4
2
|
|
|
5
3
|
/** Removes undefined/null fields, used by the models' toJSON(). */
|
|
@@ -36,7 +34,7 @@ export function extraFields(data, names) {
|
|
|
36
34
|
}
|
|
37
35
|
|
|
38
36
|
/** The SDK and its version in the "platform" query parameter of every request. */
|
|
39
|
-
export const PLATFORM = "node-sdk.
|
|
37
|
+
export const PLATFORM = "node-sdk.2.2.3";
|
|
40
38
|
|
|
41
39
|
/**
|
|
42
40
|
* Sets a header, replacing one of the same name in another case.
|
|
@@ -60,7 +58,7 @@ function messageOf(error) {
|
|
|
60
58
|
|
|
61
59
|
/**
|
|
62
60
|
* Sends a request through a fetch-compatible function and reads the response body within a time limit (also when
|
|
63
|
-
* the function ignores the abort signal
|
|
61
|
+
* the function ignores the abort signal). The status is put into `result` as soon as it is known.
|
|
64
62
|
* @param {import("./Configuration.js").FetchFunction} send
|
|
65
63
|
* @param {string} url
|
|
66
64
|
* @param {{method: string, headers: Record<string, string>, body: string}} init
|
|
@@ -68,18 +66,16 @@ function messageOf(error) {
|
|
|
68
66
|
* @param {{status: number, text: string}} result
|
|
69
67
|
*/
|
|
70
68
|
async function fetchText(send, url, init, timeout, result) {
|
|
71
|
-
const controller =
|
|
69
|
+
const controller = new AbortController();
|
|
72
70
|
let timer;
|
|
73
71
|
const expired = new Promise((resolve, reject) => {
|
|
74
72
|
timer = setTimeout(() => {
|
|
75
73
|
reject(new Error(`timeout of ${timeout} ms exceeded`));
|
|
76
|
-
|
|
77
|
-
controller.abort();
|
|
78
|
-
}
|
|
74
|
+
controller.abort();
|
|
79
75
|
}, timeout);
|
|
80
76
|
});
|
|
81
77
|
try {
|
|
82
|
-
const response = await Promise.race([send.call(globalThis, url,
|
|
78
|
+
const response = await Promise.race([send.call(globalThis, url, { ...init, signal: controller.signal }), expired]);
|
|
83
79
|
result.status = response.status;
|
|
84
80
|
result.text = await Promise.race([response.text(), expired]);
|
|
85
81
|
} finally {
|
|
@@ -87,42 +83,9 @@ async function fetchText(send, url, init, timeout, result) {
|
|
|
87
83
|
}
|
|
88
84
|
}
|
|
89
85
|
|
|
90
|
-
/**
|
|
91
|
-
* Sends a POST request with the built-in http/https modules.
|
|
92
|
-
* @param {string} url
|
|
93
|
-
* @param {Record<string, string|number>} headers
|
|
94
|
-
* @param {Buffer} payload
|
|
95
|
-
* @param {number} timeout Time limit of the whole request in milliseconds.
|
|
96
|
-
* @returns {Promise<{status: number, text: string}>}
|
|
97
|
-
*/
|
|
98
|
-
function post(url, headers, payload, timeout) {
|
|
99
|
-
return new Promise((resolve, reject) => {
|
|
100
|
-
const target = new URL(url);
|
|
101
|
-
const transport = target.protocol === "http:" ? http : https;
|
|
102
|
-
let timer;
|
|
103
|
-
const fail = (error) => {
|
|
104
|
-
clearTimeout(timer);
|
|
105
|
-
reject(error);
|
|
106
|
-
};
|
|
107
|
-
const request = transport.request(target, { method: "POST", headers }, (response) => {
|
|
108
|
-
const chunks = [];
|
|
109
|
-
response.on("data", (chunk) => chunks.push(chunk));
|
|
110
|
-
response.on("end", () => {
|
|
111
|
-
clearTimeout(timer);
|
|
112
|
-
resolve({ status: response.statusCode || 0, text: Buffer.concat(chunks).toString("utf8") });
|
|
113
|
-
});
|
|
114
|
-
response.on("error", fail);
|
|
115
|
-
response.on("aborted", () => fail(new Error("the response was aborted")));
|
|
116
|
-
});
|
|
117
|
-
timer = setTimeout(() => request.destroy(new Error(`timeout of ${timeout} ms exceeded`)), timeout);
|
|
118
|
-
request.on("error", fail);
|
|
119
|
-
request.end(payload);
|
|
120
|
-
});
|
|
121
|
-
}
|
|
122
|
-
|
|
123
86
|
/**
|
|
124
87
|
* Low level transport: every API method is a POST request with a JSON body that returns JSON. The requests go
|
|
125
|
-
* through config.fetch
|
|
88
|
+
* through config.fetch, globalThis.fetch by default.
|
|
126
89
|
*/
|
|
127
90
|
export class ApiClient {
|
|
128
91
|
/** @param {import("./Configuration.js").Configuration} config */
|
|
@@ -166,17 +129,14 @@ export class ApiClient {
|
|
|
166
129
|
* @throws {ApiError}
|
|
167
130
|
*/
|
|
168
131
|
async call(path, body = {}) {
|
|
169
|
-
const
|
|
170
|
-
|
|
132
|
+
const send = this.config.fetch || globalThis.fetch;
|
|
133
|
+
const result = { status: 0, text: "" };
|
|
171
134
|
try {
|
|
172
|
-
if (
|
|
173
|
-
|
|
174
|
-
this.config.timeout, result);
|
|
175
|
-
} else {
|
|
176
|
-
const payload = Buffer.from(json, "utf8");
|
|
177
|
-
result = await post(this.url(path), { ...this.headers(), "Content-Length": payload.length },
|
|
178
|
-
payload, this.config.timeout);
|
|
135
|
+
if (typeof send !== "function") {
|
|
136
|
+
throw new Error("fetch is not available, pass the fetch option of the configuration");
|
|
179
137
|
}
|
|
138
|
+
await fetchText(send, this.url(path), { method: "POST", headers: this.headers(), body: JSON.stringify(body ?? {}) },
|
|
139
|
+
this.config.timeout, result);
|
|
180
140
|
} catch (error) {
|
|
181
141
|
throw new ApiError(`HTTP request failed: ${messageOf(error)}`, { httpStatus: result.status, cause: error });
|
|
182
142
|
}
|
package/src/client/ApiError.js
CHANGED
|
@@ -5,11 +5,7 @@ export class ApiError extends Error {
|
|
|
5
5
|
* @param {{httpStatus?: number, errorCode?: number|null, responseBody?: object|null, cause?: unknown}} [options]
|
|
6
6
|
*/
|
|
7
7
|
constructor(message, { httpStatus = 0, errorCode = null, responseBody = null, cause } = {}) {
|
|
8
|
-
super(message);
|
|
9
|
-
if (cause !== undefined) {
|
|
10
|
-
/** The error that caused this one (set here: the "cause" option of Error needs Node.js 16.9). */
|
|
11
|
-
Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true });
|
|
12
|
-
}
|
|
8
|
+
super(message, cause === undefined ? undefined : { cause });
|
|
13
9
|
this.name = "ApiError";
|
|
14
10
|
/** HTTP status of the response, 0 when the request was not sent. */
|
|
15
11
|
this.httpStatus = httpStatus;
|
|
@@ -48,7 +48,7 @@ export interface ConfigurationOptions {
|
|
|
48
48
|
platform?: string;
|
|
49
49
|
/** Extra headers of every request; a default one of the same name (any case) is replaced. */
|
|
50
50
|
headers?: Record<string, string>;
|
|
51
|
-
/** Function the requests go through, a fetch-compatible function, default:
|
|
51
|
+
/** Function the requests go through, a fetch-compatible function, default: globalThis.fetch. */
|
|
52
52
|
fetch?: FetchFunction;
|
|
53
53
|
}
|
|
54
54
|
|
|
@@ -34,9 +34,9 @@ export class Configuration {
|
|
|
34
34
|
* @param {{baseUrl?: string, timeout?: number, userAgent?: string, platform?: string,
|
|
35
35
|
* headers?: Record<string, string>, fetch?: FetchFunction}} [options] timeout in milliseconds; platform: package
|
|
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
|
-
* one (PLATFORM); headers: extra headers of every request; fetch: a fetch-compatible function, default:
|
|
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/
|
|
39
|
+
constructor(apiKey, { baseUrl = DEFAULT_BASE_URL, timeout = 30000, userAgent = "unione-node-sdk/2.2.3", platform, headers = {}, fetch } = {}) {
|
|
40
40
|
this.apiKey = apiKey;
|
|
41
41
|
this.baseUrl = baseUrl.replace(/\/+$/, "");
|
|
42
42
|
this.timeout = timeout;
|
|
@@ -49,7 +49,7 @@ export class Configuration {
|
|
|
49
49
|
*/
|
|
50
50
|
this.headers = { ...headers };
|
|
51
51
|
/**
|
|
52
|
-
* Function the requests go through, a fetch-compatible function, default:
|
|
52
|
+
* Function the requests go through, a fetch-compatible function, default: globalThis.fetch.
|
|
53
53
|
* @type {FetchFunction | undefined}
|
|
54
54
|
*/
|
|
55
55
|
this.fetch = fetch;
|