@mailermine/node 1.0.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/CHANGELOG.md ADDED
@@ -0,0 +1,42 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@mailermine/node` will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [1.0.0] - 2026-07-18
11
+
12
+ First stable, production release. Full public-surface parity with the
13
+ MailerMine Laravel SDK (18 resources).
14
+
15
+ ### Added
16
+
17
+ - Deliverability resources: `analytics`, `events`, `messages`, `webhooks`, and `suppressions`.
18
+ - `Webhooks.verify()` for local HMAC-SHA256 signature verification.
19
+ - Marketing resources: `contacts`, `lists`, `segments`, `tags`, `audiences`, `campaigns`, `imports`, and `exports`.
20
+ - Contact helpers: `search`, `identify`, `upsert`, `subscribe`, and `unsubscribe`.
21
+ - Campaign helpers mirroring the Laravel SDK (create-with-follow-up-update, analytics slices, recipient previews, full lifecycle).
22
+ - Core platform resources: `emails`, `projects`, `apiKeys` (incl. `rotate`/`reveal`), `domains`, and `templates` (incl. `test`).
23
+ - Public `MailerMine` client with `Response`, `Collection`, `Pagination`, and typed SDK exceptions.
24
+ - Runnable examples for every resource group.
25
+
26
+ ### Changed
27
+
28
+ - **Exception encapsulation is now sealed.** Generated OpenAPI runtime errors
29
+ (`ResponseError`, `RequiredError`, `FetchError`) never escape the SDK: they
30
+ are no longer attached via `Error.cause`, and generated identifiers, response
31
+ objects, and stacks are stripped from public errors. The public exception
32
+ surface is exactly `ApiError`, `AuthenticationError`, `ValidationError`,
33
+ `PlanError`, `NotFoundError`, and `RateLimitError`.
34
+
35
+ ## [0.1.0] - 2026-07-17
36
+
37
+ ### Added
38
+
39
+ - Phase 1 SDK foundation: TypeScript project, dual ESM/CJS build via tsup, ESLint, Prettier, Vitest, and GitHub Actions CI.
40
+ - Immutable `Configuration` with `apiKey`, `baseUrl`, `timeout`, and `userAgent` (defaults aligned with the Laravel SDK).
41
+ - Repository scaffolding: `src/`, `generated/`, `tests/`, `examples/`, `docs/`, `scripts/`.
42
+ - Initial public foundation release of `@mailermine/node`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) MailerMine
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,383 @@
1
+ # @mailermine/node
2
+
3
+ Official MailerMine SDK for Node.js and TypeScript.
4
+
5
+ > **Status:** `1.0.0` — stable. Full public-surface parity with the MailerMine Laravel SDK across all 18 resources: emails, projects, API keys, domains, templates, contacts, lists, segments, tags, audiences, campaigns, imports, exports, analytics, events, messages, webhooks, and suppressions.
6
+
7
+ ## Requirements
8
+
9
+ - Node.js **20.19+**
10
+ - TypeScript **5+** (optional but recommended)
11
+
12
+ ## Installation
13
+
14
+ ```bash
15
+ npm install @mailermine/node
16
+ ```
17
+
18
+ ```bash
19
+ pnpm add @mailermine/node
20
+ ```
21
+
22
+ ```bash
23
+ yarn add @mailermine/node
24
+ ```
25
+
26
+ ## Quick Start
27
+
28
+ ```ts
29
+ import { MailerMine } from '@mailermine/node';
30
+
31
+ const mm = new MailerMine({
32
+ apiKey: process.env.MAILERMINE_API_KEY!,
33
+ });
34
+
35
+ const sent = await mm.emails.send({
36
+ from: 'MailerMine <hello@example.com>',
37
+ to: 'user@example.com',
38
+ subject: 'Welcome',
39
+ html: '<p>Hello from MailerMine</p>',
40
+ text: 'Hello from MailerMine',
41
+ });
42
+
43
+ console.log(sent.data.id);
44
+ ```
45
+
46
+ ## Configuration
47
+
48
+ ```ts
49
+ import { MailerMine, DEFAULT_BASE_URL } from '@mailermine/node';
50
+
51
+ const mm = new MailerMine({
52
+ apiKey: process.env.MAILERMINE_API_KEY!,
53
+ baseUrl: DEFAULT_BASE_URL, // https://mailermine.com/api/v1
54
+ timeout: 30_000,
55
+ userAgent: 'mailermine-node/1.0.0',
56
+ });
57
+ ```
58
+
59
+ | Option | Type | Default | Description |
60
+ | --- | --- | --- | --- |
61
+ | `apiKey` | `string` | — | Required MailerMine API key |
62
+ | `baseUrl` | `string` | `https://mailermine.com/api/v1` | API base URL |
63
+ | `timeout` | `number` | `30000` | Request timeout in milliseconds |
64
+ | `userAgent` | `string` | `mailermine-node/<version>` | User-Agent header value |
65
+
66
+ ## Emails
67
+
68
+ ```ts
69
+ await mm.emails.send({
70
+ from: 'hello@example.com',
71
+ to: ['user@example.com'],
72
+ cc: ['copy@example.com'],
73
+ bcc: ['audit@example.com'],
74
+ replyTo: 'support@example.com',
75
+ subject: 'Invoice ready',
76
+ html: '<p>Your invoice is ready.</p>',
77
+ text: 'Your invoice is ready.',
78
+ tags: ['invoice'],
79
+ metadata: { order_id: '123' },
80
+ headers: { 'X-Customer-ID': '123' },
81
+ attachments: [
82
+ {
83
+ filename: 'invoice.pdf',
84
+ content: pdfBase64,
85
+ contentType: 'application/pdf',
86
+ },
87
+ ],
88
+ scheduledAt: '2026-07-18T10:00:00Z',
89
+ });
90
+
91
+ const messages = await mm.emails.list({ status: 'delivered', perPage: 25 });
92
+ const message = await mm.emails.get(messages.items[0]!.id);
93
+ const events = await mm.emails.events(message.data.id);
94
+ ```
95
+
96
+ ## Domains
97
+
98
+ ```ts
99
+ const created = await mm.domains.create({ domain: 'mail.example.com' });
100
+ const domains = await mm.domains.list();
101
+ const domain = await mm.domains.get(created.data.id);
102
+ const verified = await mm.domains.verify(created.data.id);
103
+ const records = await mm.domains.dnsRecords(created.data.id);
104
+ const status = await mm.domains.status(created.data.id);
105
+ await mm.domains.delete(created.data.id);
106
+ ```
107
+
108
+ ## Templates
109
+
110
+ ```ts
111
+ const template = await mm.templates.create({
112
+ name: 'Welcome Email',
113
+ subject: 'Welcome {{first_name}}',
114
+ html: '<p>Hello {{first_name}}</p>',
115
+ text: 'Hello {{first_name}}',
116
+ status: 'draft',
117
+ variables: [{ name: 'first_name', type: 'string', required: true }],
118
+ });
119
+
120
+ const preview = await mm.templates.preview(template.data.id, {
121
+ variables: { first_name: 'Alex' },
122
+ });
123
+
124
+ await mm.templates.update(template.data.id, { status: 'published' });
125
+ await mm.templates.duplicate(template.data.id, { name: 'Welcome Copy' });
126
+ await mm.templates.delete(template.data.id);
127
+ ```
128
+
129
+ ## Projects
130
+
131
+ ```ts
132
+ const project = await mm.projects.create({
133
+ name: 'Production Mail',
134
+ environment: 'production',
135
+ });
136
+
137
+ const projects = await mm.projects.list();
138
+ await mm.projects.update(project.data.id, { description: 'Transactional email' });
139
+ await mm.projects.delete(project.data.id);
140
+ ```
141
+
142
+ ## API Keys
143
+
144
+ ```ts
145
+ const key = await mm.apiKeys.create(projectId, {
146
+ name: 'CI Production',
147
+ scopes: ['emails.send', 'emails.read'],
148
+ });
149
+
150
+ console.log(key.data.secret); // shown once
151
+
152
+ const keys = await mm.apiKeys.list(projectId);
153
+ await mm.apiKeys.update(projectId, key.data.id, { name: 'CI Staging' });
154
+ await mm.apiKeys.delete(projectId, key.data.id);
155
+ ```
156
+
157
+ ## Contacts
158
+
159
+ ```ts
160
+ const contact = await mm.contacts.create({
161
+ email: 'john@example.com',
162
+ firstName: 'John',
163
+ subscribed: true,
164
+ });
165
+
166
+ const found = await mm.contacts.identify('john@example.com');
167
+ const upserted = await mm.contacts.upsert({
168
+ email: 'john@example.com',
169
+ firstName: 'Jonathan',
170
+ });
171
+
172
+ await mm.contacts.subscribe(contact.data.id);
173
+ await mm.contacts.unsubscribe(contact.data.id);
174
+ const matches = await mm.contacts.search('john');
175
+ ```
176
+
177
+ ## Lists
178
+
179
+ ```ts
180
+ const list = await mm.lists.create({ name: 'Newsletter' });
181
+ await mm.lists.addContact(list.data.id, contactId);
182
+ await mm.lists.removeContact(list.data.id, [contactId]);
183
+ await mm.lists.update(list.data.id, { description: 'Weekly updates' });
184
+ ```
185
+
186
+ ## Segments
187
+
188
+ ```ts
189
+ const segment = await mm.segments.create({
190
+ name: 'Active subscribers',
191
+ rules: {
192
+ logic: 'and',
193
+ rules: [{ field: 'subscribed', operator: 'equals', value: true }],
194
+ },
195
+ });
196
+
197
+ const preview = await mm.segments.preview(segment.data.id);
198
+ const rulesPreview = await mm.segments.preview(null, {
199
+ logic: 'and',
200
+ rules: [{ field: 'subscribed', operator: 'equals', value: true }],
201
+ });
202
+ ```
203
+
204
+ ## Tags
205
+
206
+ ```ts
207
+ const tag = await mm.tags.create({ name: 'vip', color: '#111827' });
208
+ await mm.tags.assign({ contactIds: [contactId], tagIds: [tag.data.id] });
209
+ await mm.tags.remove({ contactIds: [contactId], tagIds: [tag.data.id] });
210
+ ```
211
+
212
+ ## Audiences
213
+
214
+ ```ts
215
+ const audiences = await mm.audiences.list({ page: 1 });
216
+ const audience = await mm.audiences.get('list', listId);
217
+ ```
218
+
219
+ ## Campaigns
220
+
221
+ ```ts
222
+ const campaign = await mm.campaigns.create({
223
+ name: 'March Newsletter',
224
+ subject: 'What is new',
225
+ templateId,
226
+ segmentId,
227
+ preheader: 'Inbox teaser',
228
+ });
229
+
230
+ await mm.campaigns.setSender(campaign.data.uuid, {
231
+ fromName: 'MailerMine',
232
+ fromEmail: 'hello@example.com',
233
+ });
234
+
235
+ const preview = await mm.campaigns.preview(campaign.data.uuid);
236
+ const analytics = await mm.campaigns.analytics(campaign.data.uuid);
237
+ const opens = await mm.campaigns.opens(campaign.data.uuid);
238
+ ```
239
+
240
+ ## Imports
241
+
242
+ ```ts
243
+ const job = await mm.imports.create({
244
+ file: Buffer.from('email,first_name\nada@example.com,Ada\n'),
245
+ });
246
+ const status = await mm.imports.status(job.data.id);
247
+ const recent = await mm.imports.list();
248
+ ```
249
+
250
+ ## Exports
251
+
252
+ ```ts
253
+ const exportJob = await mm.exports.create({ subscribed: true });
254
+ const status = await mm.exports.status(exportJob.data.id);
255
+ const csv = await mm.exports.download(exportJob.data.id);
256
+ ```
257
+
258
+ ## Analytics
259
+
260
+ ```ts
261
+ const overview = await mm.analytics.overview({ from: '2026-01-01', to: '2026-01-31' });
262
+ const opens = await mm.analytics.opens({ from: '2026-01-01', to: '2026-01-31' });
263
+ const clicks = await mm.analytics.clicks();
264
+ const bounces = await mm.analytics.bounces();
265
+ const engagement = await mm.analytics.engagement();
266
+ const topCampaigns = await mm.analytics.campaigns();
267
+
268
+ // Passing a campaign id delegates to campaign-level analytics.
269
+ const campaignOpens = await mm.analytics.opens({ campaign: campaignId });
270
+ ```
271
+
272
+ Also available: `deliveries`, `complaints`, `unsubscribes`, `usage`, `activity`, `messages`, `domains`, `projects`, and `providers`.
273
+
274
+ ## Events
275
+
276
+ ```ts
277
+ const events = await mm.events.list({ eventType: 'email.delivered', perPage: 50 });
278
+ const event = await mm.events.get(events.items[0]!.id);
279
+ const timeline = await mm.events.timeline(messageId);
280
+ const message = await mm.events.message(messageId);
281
+ ```
282
+
283
+ ## Messages
284
+
285
+ ```ts
286
+ const logs = await mm.messages.list({ status: 'delivered', perPage: 25 });
287
+ const message = await mm.messages.get(logs.items[0]!.id);
288
+ const results = await mm.messages.search('user@example.com');
289
+ const events = await mm.messages.events(message.data.id);
290
+ ```
291
+
292
+ ## Webhooks
293
+
294
+ ```ts
295
+ const webhook = await mm.webhooks.create({
296
+ name: 'Delivery events',
297
+ url: 'https://example.com/webhooks/mailermine',
298
+ subscribedEvents: ['email.delivered', 'email.bounced'],
299
+ });
300
+
301
+ console.log(webhook.data.signingSecret); // shown once
302
+
303
+ const deliveries = await mm.webhooks.deliveries(webhook.data.id);
304
+ await mm.webhooks.disable(webhook.data.id);
305
+ await mm.webhooks.rotateSecret(webhook.data.id);
306
+
307
+ // Verify an incoming signature locally (HMAC-SHA256).
308
+ import { Webhooks } from '@mailermine/node';
309
+ const valid = Webhooks.verify(rawBody, signatureHeader, signingSecret);
310
+ ```
311
+
312
+ Also available: `get`, `list`, `update`, `delete`, `test`, `enable`, `delivery`, `logs`, `failures`, `replay`, and `retry`.
313
+
314
+ ## Suppressions
315
+
316
+ ```ts
317
+ const added = await mm.suppressions.add({ email: 'bounce@example.com', reason: 'bounce' });
318
+ const list = await mm.suppressions.list({ perPage: 50 });
319
+ const check = await mm.suppressions.check('bounce@example.com');
320
+ console.log(check.data.suppressed);
321
+ await mm.suppressions.remove(added.data.id);
322
+ ```
323
+
324
+ ## Responses & errors
325
+
326
+ - Single objects return `Response<T>`
327
+ - Lists return `Collection<T>` with a `Pagination` object
328
+ - Generated OpenAPI types never leak into the public API
329
+
330
+ | Status | Exception |
331
+ | --- | --- |
332
+ | 401 | `AuthenticationError` |
333
+ | 403 | `PlanError` |
334
+ | 404 | `NotFoundError` |
335
+ | 422 | `ValidationError` |
336
+ | 429 | `RateLimitError` |
337
+ | 5xx / other | `ApiError` |
338
+
339
+ ## Development
340
+
341
+ ```bash
342
+ npm install
343
+ npm run generate
344
+ npm run lint
345
+ npm run typecheck
346
+ npm run test
347
+ npm run build
348
+ ```
349
+
350
+ Or run the full quality gate:
351
+
352
+ ```bash
353
+ npm run check
354
+ ```
355
+
356
+ ## Repository layout
357
+
358
+ ```text
359
+ src/ Handwritten public SDK
360
+ generated/ OpenAPI client (do not edit by hand)
361
+ tests/ Vitest suite (Laravel-style mocked HTTP)
362
+ examples/ Runnable usage examples
363
+ docs/ Extended documentation
364
+ scripts/ Generation and maintenance scripts
365
+ ```
366
+
367
+ ## Resource coverage
368
+
369
+ All 18 Laravel SDK resources are available on the client:
370
+
371
+ `emails`, `projects`, `apiKeys`, `domains`, `templates`, `contacts`, `lists`,
372
+ `segments`, `tags`, `audiences`, `campaigns`, `imports`, `exports`,
373
+ `analytics`, `events`, `messages`, `webhooks`, `suppressions`.
374
+
375
+ ## Contributing
376
+
377
+ See [CONTRIBUTING.md](./CONTRIBUTING.md).
378
+
379
+ ## License
380
+
381
+ [MIT](./LICENSE) © MailerMine
382
+ # mailermine-node
383
+ # mailermine-node