unitpost 0.0.0 → 0.2.0

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/README.md CHANGED
@@ -1,14 +1,177 @@
1
1
  # unitpost
2
2
 
3
- This name is reserved for **[Unitpost](https://unitpost.com)**.
3
+ Official [Unitpost](https://www.unitpost.com) SDK for Node.js. Send email and manage
4
+ contacts, segments, campaigns, templates, domains, suppressions, and webhooks.
4
5
 
5
- The official Unitpost packages are published under the **`@unitpost`** scope:
6
+ ## Install
6
7
 
7
- - [`@unitpost/email`](https://www.npmjs.com/package/@unitpost/email)
8
+ ```bash
9
+ npm install unitpost
10
+ ```
8
11
 
9
- This unscoped `unitpost` package is an intentionally empty placeholder and exports
10
- nothing. Install the scoped package you need instead:
12
+ Requires Node.js 18+ (uses the built-in `fetch`).
11
13
 
12
- ```bash
13
- npm install @unitpost/email
14
+ ## Quick start
15
+
16
+ ```ts
17
+ import { Unitpost } from "unitpost";
18
+
19
+ const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);
20
+
21
+ const { data, error } = await unitpost.email.send({
22
+ from: "Acme <you@yourdomain.com>", // bare address works too
23
+ to: "customer@example.com",
24
+ subject: "Hello",
25
+ html: "<p>It works!</p>",
26
+ });
27
+
28
+ if (error) {
29
+ console.error(error.code, error.message);
30
+ } else {
31
+ console.log("sent", data.id);
32
+ }
14
33
  ```
34
+
35
+ Every method returns `{ data, error }` — an API-level failure populates `error`
36
+ (a typed `UnitpostError`) instead of throwing, so you never need a `try/catch`
37
+ around a normal request.
38
+
39
+ ## Authentication
40
+
41
+ Pass the key directly, or set `UNITPOST_API_KEY` and construct with no argument:
42
+
43
+ ```ts
44
+ const unitpost = new Unitpost(); // reads process.env.UNITPOST_API_KEY
45
+ ```
46
+
47
+ Create a key at [unitpost.com → Settings → API keys](https://www.unitpost.com).
48
+ Options: `new Unitpost({ apiKey, baseUrl, timeout, fetch, headers, maxRetries, retryBaseDelay, maxRetryDelay })`.
49
+
50
+ ## Client surface
51
+
52
+ | Accessor | Covers |
53
+ | --- | --- |
54
+ | `emails` | Send, batch, list, get, update, stats, inbound (`received*`) |
55
+ | `contacts` | CRUD, import jobs |
56
+ | `contactFields` | Custom field definitions |
57
+ | `segments` | Segments + membership |
58
+ | `topics` | Topics + contact topic prefs |
59
+ | `campaigns` | Draft, schedule, send, pause/resume |
60
+ | `templates` | Template CRUD |
61
+ | `brandKits` | Brand kit |
62
+ | `domains` | Domains + verify |
63
+ | `webhooks` | Endpoints + `verify()` |
64
+ | `apiKeys` | API key management |
65
+ | `suppressions` | Suppression list |
66
+ | `usage` | Billing-period usage snapshot |
67
+
68
+ ## Pagination
69
+
70
+ List endpoints are cursor-paginated. Use `list()` for one page or `listAll()`
71
+ to async-iterate every row:
72
+
73
+ ```ts
74
+ for await (const contact of unitpost.contacts.listAll()) {
75
+ console.log(contact.email);
76
+ }
77
+ ```
78
+
79
+ ## Suppressions
80
+
81
+ The suppression list holds addresses that are excluded from every send — single,
82
+ batch, and campaign, including cc/bcc — case-insensitively. Hard bounces and spam
83
+ complaints are added automatically; you can also add your own:
84
+
85
+ ```ts
86
+ // Suppress one address, or many in a single call (idempotent — re-adding is a no-op).
87
+ await unitpost.suppressions.create({ email: "bounced@example.com", reason: "manual" });
88
+ await unitpost.suppressions.create({ emails: ["a@example.com", "b@example.com"] });
89
+
90
+ // Look one up by id or email; list (optionally filter scope); un-suppress.
91
+ const { data } = await unitpost.suppressions.get("bounced@example.com");
92
+ for await (const s of unitpost.suppressions.listAll()) console.log(s.email, s.reason);
93
+ await unitpost.suppressions.delete("bounced@example.com");
94
+ ```
95
+
96
+ `reason` accepts `manual`, `import`, or `api` — the engine-written `bounce` and
97
+ `complaint` reasons are read-only. Unitpost-wide (`platform`) entries are visible
98
+ but can't be removed via the API.
99
+
100
+ ## Verifying webhooks
101
+
102
+ Deliveries are svix-compatible. Verify the raw request body against your
103
+ endpoint's signing secret:
104
+
105
+ ```ts
106
+ import { verifyWebhook } from "unitpost";
107
+
108
+ const event = verifyWebhook({
109
+ payload: rawBody, // the raw request body string
110
+ secret: process.env.UNITPOST_WEBHOOK_SECRET,
111
+ headers: req.headers,
112
+ });
113
+ ```
114
+
115
+ You can also call it from the client (Resend-style alias):
116
+
117
+ ```ts
118
+ const event = unitpost.webhooks.verify({ payload: rawBody, secret, headers: req.headers });
119
+ ```
120
+
121
+ ## Idempotency
122
+
123
+ `emails.send` and `emails.batch` are safe to retry by default: if you don't pass
124
+ an idempotency key, the SDK generates one for you so an automatic retry can never
125
+ send twice. Pass your own to dedupe across separate calls (e.g. a user
126
+ double-clicks "send"):
127
+
128
+ ```ts
129
+ await unitpost.email.send({ ... }, { idempotencyKey: crypto.randomUUID() });
130
+ await unitpost.email.batch([ ... ], { idempotencyKey: crypto.randomUUID() });
131
+ ```
132
+
133
+ > The server dedupes on `(workspace, idempotency key)` for 24h and replays the
134
+ > original result instead of re-sending — for a single send that's the email id,
135
+ > for a batch the full list envelope.
136
+
137
+ ## Retries
138
+
139
+ Transient failures are retried automatically: `429`, `5xx`, and transport errors
140
+ (timeouts / network) retry up to `maxRetries` times (default `2`). A `429`/`503`
141
+ `Retry-After` is honored; otherwise the client uses exponential backoff with full
142
+ jitter. Client errors (`401`/`403`/`404`/`409`/`422`) are never retried.
143
+
144
+ Only requests that are **safe to replay** are retried: `GET`s and writes that
145
+ carry an idempotency key (which `emails.send` and `emails.batch` always do — see
146
+ above). Any other keyless write is never auto-retried.
147
+
148
+ ```ts
149
+ // Defaults shown; set maxRetries: 0 to disable.
150
+ const unitpost = new Unitpost({ maxRetries: 2, retryBaseDelay: 500, maxRetryDelay: 20_000 });
151
+ ```
152
+
153
+ ## Type-safety and the API contract
154
+
155
+ Request/response types are generated 1:1 from the public OpenAPI spec and
156
+ exported under `Models`. The SDK plumbing is regenerated from that spec and
157
+ CI-gated, so the SDK never silently drifts from the API.
158
+
159
+ ## Resources
160
+
161
+ | | |
162
+ | --- | --- |
163
+ | Docs + API reference | https://www.unitpost.com/docs |
164
+ | Product / SMTP / MCP guides | https://www.unitpost.com/guides |
165
+ | OpenAPI JSON | https://www.unitpost.com/api/v1/openapi.json |
166
+ | LLM index | https://www.unitpost.com/llms.txt |
167
+ | Dashboard / API keys | https://www.unitpost.com |
168
+ | Email components (`@unitpost/email`) | https://www.unitpost.com/components |
169
+ | Template gallery | https://www.unitpost.com/templates/gallery |
170
+ | Playground | https://www.unitpost.com/playground |
171
+ | Migration Assistant | https://www.unitpost.com/migration |
172
+ | MCP + Agent Skills | https://www.unitpost.com/guides#ai-mcp · https://www.unitpost.com/guides#ai-skills |
173
+ | Support | support@unitpost.com |
174
+
175
+ ## License
176
+
177
+ MIT