@antelopejs/interface-email 0.0.6 → 0.1.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/dist/index.d.ts +20 -4
- package/dist/index.js.map +1 -1
- package/docs/1.introduction.md +27 -5
- package/docs/2.sending-emails.md +35 -14
- package/docs/3.attachments.md +38 -21
- package/docs/assets/message-lifecycle.svg +19 -0
- package/package.json +14 -4
- package/skills/email-interface/SKILL.md +1 -1
- package/skills/email-interface/cases.json +49 -0
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A value JSON can represent: a string, number, boolean, `null`, an array of
|
|
3
|
+
* JSON values, or a {@link JsonObject}. `Date`, `Buffer`, functions and class
|
|
4
|
+
* instances are not JSON values; convert them first (for example
|
|
5
|
+
* `date.toISOString()`).
|
|
6
|
+
*/
|
|
7
|
+
export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
|
|
8
|
+
/**
|
|
9
|
+
* String keys mapped to JSON values. A key whose value is `undefined` is
|
|
10
|
+
* accepted so an optional field can be passed as is; `JSON.stringify` drops
|
|
11
|
+
* it. An object typed as an `interface` is not assignable (it has no index
|
|
12
|
+
* signature); declare it with a `type` alias or spread it into a literal.
|
|
13
|
+
*/
|
|
14
|
+
export type JsonObject = {
|
|
15
|
+
[key: string]: JsonValue | undefined;
|
|
16
|
+
};
|
|
1
17
|
export interface EmailAddressObject {
|
|
2
18
|
email: string;
|
|
3
19
|
name?: string;
|
|
@@ -81,7 +97,7 @@ export interface EmailParams {
|
|
|
81
97
|
/** Schedule for later delivery */
|
|
82
98
|
schedule?: ScheduleOptions;
|
|
83
99
|
/** Provider-specific options (use sparingly) */
|
|
84
|
-
providerOptions?:
|
|
100
|
+
providerOptions?: JsonObject;
|
|
85
101
|
}
|
|
86
102
|
/** Reference to a template hosted by the provider */
|
|
87
103
|
export interface ProviderTemplate {
|
|
@@ -105,9 +121,9 @@ export interface TemplateEmailParams {
|
|
|
105
121
|
/** Template to use */
|
|
106
122
|
template: ProviderTemplate | InlineTemplate;
|
|
107
123
|
/** Variables for template substitution */
|
|
108
|
-
variables?:
|
|
124
|
+
variables?: JsonObject;
|
|
109
125
|
/** Per-recipient variables (keyed by email address) */
|
|
110
|
-
recipientVariables?: Record<string,
|
|
126
|
+
recipientVariables?: Record<string, JsonObject>;
|
|
111
127
|
from?: EmailAddress;
|
|
112
128
|
replyTo?: EmailAddress | EmailAddress[];
|
|
113
129
|
cc?: EmailAddress | EmailAddress[];
|
|
@@ -120,7 +136,7 @@ export interface TemplateEmailParams {
|
|
|
120
136
|
tags?: string[];
|
|
121
137
|
metadata?: Record<string, string>;
|
|
122
138
|
schedule?: ScheduleOptions;
|
|
123
|
-
providerOptions?:
|
|
139
|
+
providerOptions?: JsonObject;
|
|
124
140
|
}
|
|
125
141
|
/** Single message in a batch */
|
|
126
142
|
export interface BatchEmailMessage extends EmailParams {
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAkS/D;;;;;;;;;;GAUG;AACU,QAAA,IAAI,GAAG,IAAA,kCAAiB,GAAgB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACU,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAqB,CAAC;AAEhE;;;;;;;;;;GAUG;AACU,QAAA,YAAY,GAAG,IAAA,kCAAiB,GAAwB,CAAC;AAEtE;;;;;;;;;GASG;AACU,QAAA,eAAe,GAAG,IAAA,kCAAiB,GAA2B,CAAC"}
|
package/docs/1.introduction.md
CHANGED
|
@@ -1,6 +1,20 @@
|
|
|
1
1
|
# Introduction
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Send transactional messages, templates, and batches through one provider-neutral contract. `@antelopejs/interface-email` defines the request and response types; an implementing module supplies the email provider and its configuration.
|
|
4
|
+
|
|
5
|
+
## Choose your sending path
|
|
6
|
+
|
|
7
|
+
| Your task | Start here |
|
|
8
|
+
| -------------------------------------------------- | -------------------------------------------------------------- |
|
|
9
|
+
| Send a welcome email or receipt | [Send a message](./2.sending-emails.md#the-emailparams-object) |
|
|
10
|
+
| Personalize provider-hosted or inline content | [Template emails](./2.sending-emails.md#template-emails) |
|
|
11
|
+
| Send several messages and inspect partial failures | [Batch sending](./2.sending-emails.md#batch-sending) |
|
|
12
|
+
| Include a document or inline image | [Attachments](./3.attachments.md) |
|
|
13
|
+
| Keep optional features portable | [Provider capabilities](#provider-capabilities) |
|
|
14
|
+
|
|
15
|
+
{width="480"}
|
|
16
|
+
|
|
17
|
+
**Before sending:** configure an implementation with credentials and an authorized sender. Installing this contract alone does not connect an email service. Examples use placeholder recipients and do not send mail from this documentation.
|
|
4
18
|
|
|
5
19
|
## Core Concepts
|
|
6
20
|
|
|
@@ -13,7 +27,7 @@ The interface separates email operations into four functions:
|
|
|
13
27
|
| `SendTemplate` | Send an email rendered from a template |
|
|
14
28
|
| `GetCapabilities` | Query the provider's supported features and limits |
|
|
15
29
|
|
|
16
|
-
|
|
30
|
+
The sending functions return typed delivery responses. `GetCapabilities` returns feature flags and limits instead. A successful send means the provider accepted the request; inspect `status` rather than treating acceptance as confirmed delivery.
|
|
17
31
|
|
|
18
32
|
## Installation
|
|
19
33
|
|
|
@@ -30,6 +44,8 @@ Recipients, senders, and reply-to addresses all accept the `EmailAddress` type.
|
|
|
30
44
|
Pass an email address directly as a string:
|
|
31
45
|
|
|
32
46
|
```ts
|
|
47
|
+
import type { EmailAddress } from "@antelopejs/interface-email";
|
|
48
|
+
|
|
33
49
|
const to: EmailAddress = "user@example.com";
|
|
34
50
|
```
|
|
35
51
|
|
|
@@ -102,23 +118,29 @@ The `ProviderFeatures` object includes the following flags:
|
|
|
102
118
|
Check capabilities before using optional features to ensure your code works across providers:
|
|
103
119
|
|
|
104
120
|
```ts
|
|
105
|
-
import {
|
|
121
|
+
import {
|
|
122
|
+
GetCapabilities,
|
|
123
|
+
Send,
|
|
124
|
+
type EmailParams,
|
|
125
|
+
} from "@antelopejs/interface-email";
|
|
106
126
|
|
|
107
127
|
const caps = await GetCapabilities();
|
|
108
128
|
|
|
109
|
-
const params:
|
|
129
|
+
const params: EmailParams = {
|
|
110
130
|
to: "user@example.com",
|
|
111
131
|
subject: "Hello",
|
|
112
132
|
html: "<p>Welcome!</p>",
|
|
113
133
|
};
|
|
114
134
|
|
|
115
135
|
if (caps.features.scheduling) {
|
|
116
|
-
params.schedule = { sendAt: new Date(
|
|
136
|
+
params.schedule = { sendAt: new Date(Date.now() + 60 * 60 * 1000) };
|
|
117
137
|
}
|
|
118
138
|
|
|
119
139
|
await Send(params);
|
|
120
140
|
```
|
|
121
141
|
|
|
142
|
+
Capability limits are optional: `maxRecipients`, `maxBatchSize`, `maxAttachmentSize`, and `maxEmailSize` may be absent. Size limits are in bytes. An absent limit is not a promise of unlimited capacity; check your provider configuration. `version` is optional provider metadata.
|
|
143
|
+
|
|
122
144
|
## Next Steps
|
|
123
145
|
|
|
124
146
|
- [Sending Emails](./2.sending-emails.md) -- Learn about all email parameters, templates, batch sending, and delivery responses.
|
package/docs/2.sending-emails.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
The interface provides three sending functions: `Send` for single emails, `SendTemplate` for template-based emails, and `SendBatch` for multiple emails in one operation.
|
|
4
4
|
|
|
5
|
+
For a first message, start with [`EmailParams`](#the-emailparams-object), then inspect the [response](#email-response). Add [templates](#template-emails), [batches](#batch-sending), or optional fields only when the workflow needs them. Optional features depend on [provider capabilities](./1.introduction.md#provider-capabilities).
|
|
6
|
+
|
|
5
7
|
## The `EmailParams` Object
|
|
6
8
|
|
|
7
9
|
The `Send` function accepts an `EmailParams` object. Only `to` and `subject` are required -- all other fields are optional.
|
|
@@ -15,8 +17,19 @@ const response = await Send({
|
|
|
15
17
|
html: "<h1>Welcome!</h1><p>Thanks for joining.</p>",
|
|
16
18
|
text: "Welcome! Thanks for joining.",
|
|
17
19
|
});
|
|
20
|
+
|
|
21
|
+
if (!response.success) {
|
|
22
|
+
throw new Error(
|
|
23
|
+
response.error?.message ?? "The provider did not accept the email",
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
console.log(response.status); // Acceptance is not proof of inbox delivery.
|
|
18
27
|
```
|
|
19
28
|
|
|
29
|
+
This example uses the configured default sender. Handle rejected promises at your
|
|
30
|
+
application boundary as well as unsuccessful responses. See [Email Response](#email-response)
|
|
31
|
+
for optional fields and retry precautions.
|
|
32
|
+
|
|
20
33
|
### Required Fields
|
|
21
34
|
|
|
22
35
|
| Field | Type | Description |
|
|
@@ -26,7 +39,7 @@ const response = await Send({
|
|
|
26
39
|
|
|
27
40
|
### Content Fields
|
|
28
41
|
|
|
29
|
-
Provide at least one of `text` or `html
|
|
42
|
+
Provide at least one of `text` or `html`, even though the TypeScript type makes both optional. Including both gives readers a plain-text alternative to HTML.
|
|
30
43
|
|
|
31
44
|
| Field | Type | Description |
|
|
32
45
|
| ------ | -------- | --------------- |
|
|
@@ -66,13 +79,13 @@ await Send({
|
|
|
66
79
|
|
|
67
80
|
## Email Priority
|
|
68
81
|
|
|
69
|
-
The `priority` field
|
|
82
|
+
The `priority` field requests a priority from providers that support it. It does not guarantee faster delivery. Check `features.priority` on the awaited provider capabilities before relying on this option.
|
|
70
83
|
|
|
71
|
-
| Value | Description
|
|
72
|
-
| ---------- |
|
|
73
|
-
| `"high"` |
|
|
74
|
-
| `"normal"` | Standard delivery priority (default)
|
|
75
|
-
| `"low"` | Non-urgent emails such as newsletters
|
|
84
|
+
| Value | Description |
|
|
85
|
+
| ---------- | ------------------------------------------- |
|
|
86
|
+
| `"high"` | Request high priority for an urgent message |
|
|
87
|
+
| `"normal"` | Standard delivery priority (default) |
|
|
88
|
+
| `"low"` | Non-urgent emails such as newsletters |
|
|
76
89
|
|
|
77
90
|
```ts
|
|
78
91
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -128,13 +141,15 @@ await Send({
|
|
|
128
141
|
subject: "Monday Standup Reminder",
|
|
129
142
|
text: "Standup in 15 minutes.",
|
|
130
143
|
schedule: {
|
|
131
|
-
sendAt: new Date("
|
|
144
|
+
sendAt: new Date("2027-04-05T06:45:00Z"),
|
|
132
145
|
timezone: "Europe/Paris",
|
|
133
146
|
},
|
|
134
147
|
});
|
|
135
148
|
```
|
|
136
149
|
|
|
137
|
-
> **Note:** Check `GetCapabilities().features.scheduling` before using scheduling to confirm the provider supports it.
|
|
150
|
+
> **Note:** Check `(await GetCapabilities()).features.scheduling` before using scheduling to confirm the provider supports it.
|
|
151
|
+
|
|
152
|
+
Await `GetCapabilities()` before reading its flags. Use an explicit UTC offset when constructing a `Date`; the example is 08:45 in Paris on that date. A `timezone` field does not change how JavaScript parses a timezone-less date string.
|
|
138
153
|
|
|
139
154
|
## Tags and Metadata
|
|
140
155
|
|
|
@@ -162,7 +177,7 @@ await Send({
|
|
|
162
177
|
|
|
163
178
|
## Provider Options
|
|
164
179
|
|
|
165
|
-
The `providerOptions` field passes provider-specific configuration that falls outside the standard interface. Use it sparingly, as it reduces portability.
|
|
180
|
+
The `providerOptions` field passes provider-specific configuration that falls outside the standard interface. Use it sparingly, as it reduces portability. The value is a `JsonObject`: every nested value must be a string, number, boolean, `null`, an array of such values, or an object of them. A key whose value is `undefined` is accepted, so an optional field can be passed as is; the provider drops it.
|
|
166
181
|
|
|
167
182
|
```ts
|
|
168
183
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -216,6 +231,8 @@ const response = await SendTemplate({
|
|
|
216
231
|
});
|
|
217
232
|
```
|
|
218
233
|
|
|
234
|
+
Template variables are a `JsonObject` too, so `variables` and each `recipientVariables` entry cannot carry a `Date`, a `Buffer` or a function. Convert such a value (for example with `toISOString()`) before sending. An object declared with an `interface` is rejected because it has no index signature: declare it with a `type` alias or spread it into a literal (`{ ...user }`).
|
|
235
|
+
|
|
219
236
|
### Per-recipient variables
|
|
220
237
|
|
|
221
238
|
When sending to multiple recipients, provide unique variable values for each one using `recipientVariables`:
|
|
@@ -246,13 +263,13 @@ const result = await SendBatch({
|
|
|
246
263
|
{
|
|
247
264
|
to: "alice@example.com",
|
|
248
265
|
subject: "Your invoice",
|
|
249
|
-
html: "<p>
|
|
266
|
+
html: "<p>Your invoice #001 is ready in your account.</p>",
|
|
250
267
|
batchId: "invoice-001",
|
|
251
268
|
},
|
|
252
269
|
{
|
|
253
270
|
to: "bob@example.com",
|
|
254
271
|
subject: "Your invoice",
|
|
255
|
-
html: "<p>
|
|
272
|
+
html: "<p>Your invoice #002 is ready in your account.</p>",
|
|
256
273
|
batchId: "invoice-002",
|
|
257
274
|
},
|
|
258
275
|
],
|
|
@@ -302,9 +319,11 @@ The `Send` and `SendTemplate` functions return an `EmailResponse` object:
|
|
|
302
319
|
|
|
303
320
|
The `EmailStatus` type includes these values: `"queued"`, `"sent"`, `"delivered"`, `"failed"`, `"rejected"`, `"scheduled"`, and `"unknown"`.
|
|
304
321
|
|
|
322
|
+
Only `success` and `status` are required on `EmailResponse`. Message IDs, errors, timestamps, and provider names may be absent. In a batch, each result also has an `index` into the original messages and a `recipient`; `batchId` is optional. The batch-level `success` is true only when every message succeeds.
|
|
323
|
+
|
|
305
324
|
### Error handling
|
|
306
325
|
|
|
307
|
-
When `success` is `false`, the `error` field
|
|
326
|
+
When `success` is `false`, inspect the optional `error` field for an `EmailError` object:
|
|
308
327
|
|
|
309
328
|
```ts
|
|
310
329
|
import { Send } from "@antelopejs/interface-email";
|
|
@@ -319,11 +338,13 @@ if (!response.success && response.error) {
|
|
|
319
338
|
console.error(`Error [${response.error.code}]: ${response.error.message}`);
|
|
320
339
|
|
|
321
340
|
if (response.error.retryable) {
|
|
322
|
-
//
|
|
341
|
+
// A retry may succeed; apply your retry and duplicate-send policy.
|
|
323
342
|
}
|
|
324
343
|
}
|
|
325
344
|
```
|
|
326
345
|
|
|
346
|
+
`retryable` is a hint, not an idempotency guarantee. Retrying can send another message; the interface does not define a deduplication key. `EmailError` requires `code` and `message`, with optional `field` and `retryable`. Also handle rejected promises from the configured implementation.
|
|
347
|
+
|
|
327
348
|
## Next Steps
|
|
328
349
|
|
|
329
350
|
- [Attachments](./3.attachments.md) -- Learn how to attach files using buffers, base64, file paths, or URLs.
|
package/docs/3.attachments.md
CHANGED
|
@@ -2,16 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
The interface supports four attachment types, each suited to a different source of file data. All types share a common `BaseAttachment` structure and are passed through the `attachments` field of `EmailParams`.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Choose the source of the bytes
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
| You already have | Use | Supply |
|
|
8
|
+
| -------------------------------------- | ------------------ | ------------------------------------------ |
|
|
9
|
+
| Bytes in memory | `BufferAttachment` | `content: Buffer` |
|
|
10
|
+
| Base64-encoded bytes | `Base64Attachment` | `content: string` and `encoding: "base64"` |
|
|
11
|
+
| A file available to the implementation | `PathAttachment` | `path` |
|
|
12
|
+
| A file reachable by the implementation | `UrlAttachment` | `url` |
|
|
8
13
|
|
|
9
|
-
|
|
10
|
-
| ------------- | --------- | -------- | ----------------------------------------------------------------- |
|
|
11
|
-
| `filename` | `string` | Yes | The filename shown to the recipient |
|
|
12
|
-
| `contentType` | `string` | No | MIME type (e.g., `"application/pdf"`) |
|
|
13
|
-
| `cid` | `string` | No | Content-ID for inline images (reference in HTML as `cid:yourCid`) |
|
|
14
|
-
| `inline` | `boolean` | No | If `true`, embed in the HTML body instead of attaching as a file |
|
|
14
|
+
Paths are server-side paths, not paths on the recipient's computer. Use trusted or validated paths and URLs; do not let untrusted input select arbitrary local files or internal network addresses. Check provider size limits before sending.
|
|
15
15
|
|
|
16
16
|
## Attachment Types
|
|
17
17
|
|
|
@@ -20,14 +20,17 @@ Every attachment type extends `BaseAttachment`, which defines shared metadata fi
|
|
|
20
20
|
Use `BufferAttachment` when you have file data in memory as a Node.js `Buffer`. This is common when generating files dynamically or reading from streams.
|
|
21
21
|
|
|
22
22
|
```ts
|
|
23
|
-
import { Send, BufferAttachment } from "@antelopejs/interface-email";
|
|
23
|
+
import { Send, type BufferAttachment } from "@antelopejs/interface-email";
|
|
24
24
|
|
|
25
|
-
const
|
|
25
|
+
const reportBuffer = Buffer.from(
|
|
26
|
+
"Quarterly report\nRevenue: 12500 EUR\n",
|
|
27
|
+
"utf8",
|
|
28
|
+
);
|
|
26
29
|
|
|
27
30
|
const attachment: BufferAttachment = {
|
|
28
|
-
filename: "report.
|
|
29
|
-
contentType: "
|
|
30
|
-
content:
|
|
31
|
+
filename: "report.txt",
|
|
32
|
+
contentType: "text/plain",
|
|
33
|
+
content: reportBuffer,
|
|
31
34
|
};
|
|
32
35
|
|
|
33
36
|
await Send({
|
|
@@ -46,16 +49,16 @@ Use `Base64Attachment` when you have file data encoded as a base64 string. Set t
|
|
|
46
49
|
import { Send, Base64Attachment } from "@antelopejs/interface-email";
|
|
47
50
|
|
|
48
51
|
const attachment: Base64Attachment = {
|
|
49
|
-
filename: "
|
|
50
|
-
contentType: "
|
|
51
|
-
content: "
|
|
52
|
+
filename: "notes.txt",
|
|
53
|
+
contentType: "text/plain",
|
|
54
|
+
content: "SGVsbG8h", // Base64 for "Hello!"
|
|
52
55
|
encoding: "base64",
|
|
53
56
|
};
|
|
54
57
|
|
|
55
58
|
await Send({
|
|
56
59
|
to: "user@example.com",
|
|
57
|
-
subject: "
|
|
58
|
-
text: "
|
|
60
|
+
subject: "Meeting Notes",
|
|
61
|
+
text: "Notes attached.",
|
|
59
62
|
attachments: [attachment],
|
|
60
63
|
});
|
|
61
64
|
```
|
|
@@ -106,10 +109,13 @@ await Send({
|
|
|
106
109
|
|
|
107
110
|
Inline attachments embed images directly in the HTML body using Content-ID references. Set `inline` to `true` and assign a `cid` value, then reference it in your HTML with the `cid:` protocol.
|
|
108
111
|
|
|
112
|
+
The following example reads a real PNG at `./assets/logo.png`, relative to the server's working directory. Supply that file before running it.
|
|
113
|
+
|
|
109
114
|
```ts
|
|
110
|
-
import {
|
|
115
|
+
import { readFile } from "node:fs/promises";
|
|
116
|
+
import { Send } from "@antelopejs/interface-email";
|
|
111
117
|
|
|
112
|
-
const logoBuffer =
|
|
118
|
+
const logoBuffer = await readFile("./assets/logo.png");
|
|
113
119
|
|
|
114
120
|
await Send({
|
|
115
121
|
to: "user@example.com",
|
|
@@ -132,7 +138,7 @@ await Send({
|
|
|
132
138
|
});
|
|
133
139
|
```
|
|
134
140
|
|
|
135
|
-
> **Note:** Check `GetCapabilities().features.inlineAttachments` to confirm the provider supports inline images.
|
|
141
|
+
> **Note:** Check `(await GetCapabilities()).features.inlineAttachments` to confirm the provider supports inline images.
|
|
136
142
|
|
|
137
143
|
## Multiple Attachments
|
|
138
144
|
|
|
@@ -165,6 +171,17 @@ await Send({
|
|
|
165
171
|
});
|
|
166
172
|
```
|
|
167
173
|
|
|
174
|
+
## The `BaseAttachment` Interface
|
|
175
|
+
|
|
176
|
+
Every attachment requires a filename. These shared fields apply to all four sources:
|
|
177
|
+
|
|
178
|
+
| Field | Type | Required | Description |
|
|
179
|
+
| ------------- | --------- | -------- | ----------------------------------------------------------------- |
|
|
180
|
+
| `filename` | `string` | Yes | The filename shown to the recipient |
|
|
181
|
+
| `contentType` | `string` | No | MIME type (e.g., `"application/pdf"`) |
|
|
182
|
+
| `cid` | `string` | No | Content-ID for inline images (reference in HTML as `cid:yourCid`) |
|
|
183
|
+
| `inline` | `boolean` | No | If `true`, embed in the HTML body instead of attaching as a file |
|
|
184
|
+
|
|
168
185
|
## The `Attachment` Union Type
|
|
169
186
|
|
|
170
187
|
The `Attachment` type is a union of all four attachment interfaces:
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="480" height="650" viewBox="0 0 480 650" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">From message to provider response</title>
|
|
3
|
+
<desc id="desc">Send, SendTemplate, and SendBatch lead to a configured provider. Inspect acceptance, status, and per-message errors. Acceptance is not proof of inbox delivery.</desc>
|
|
4
|
+
<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0 8 4 0 8" fill="#627d98"/></marker></defs>
|
|
5
|
+
<rect width="480" height="650" rx="16" fill="#f4f7fb"/>
|
|
6
|
+
<g font-family="system-ui, sans-serif" fill="#17324d" font-size="18">
|
|
7
|
+
<text x="24" y="36" font-size="24" font-weight="700">Choose content.</text><text x="24" y="65" font-size="24" font-weight="700">Inspect the outcome.</text>
|
|
8
|
+
<text x="24" y="96">Configured email provider required</text>
|
|
9
|
+
<rect x="24" y="118" width="432" height="132" rx="10" fill="#e2edf8" stroke="#b0c9e0"/>
|
|
10
|
+
<text x="44" y="153" font-size="20" font-weight="600">Send · one message</text><text x="44" y="190" font-size="20" font-weight="600">SendTemplate · from a template</text><text x="44" y="227" font-size="20" font-weight="600">SendBatch · multiple messages</text>
|
|
11
|
+
<path d="M240 250V284" stroke="#627d98" stroke-width="2" marker-end="url(#arrow)"/>
|
|
12
|
+
<rect x="24" y="294" width="432" height="86" rx="10" fill="#17324d"/>
|
|
13
|
+
<text x="44" y="328" fill="#fff" font-size="22" font-weight="700">Email provider</text><text x="44" y="357" fill="#d5e5f3">Capabilities + limits</text>
|
|
14
|
+
<path d="M240 380V414" stroke="#627d98" stroke-width="2" marker-end="url(#arrow)"/>
|
|
15
|
+
<rect x="24" y="424" width="432" height="116" rx="10" fill="#e2f3ec" stroke="#91c7ae"/>
|
|
16
|
+
<text x="44" y="456" font-size="22" font-weight="700">Read the response</text><text x="44" y="486">success + status · optional ID and error</text><text x="44" y="516">Batch: inspect each result</text>
|
|
17
|
+
<rect x="24" y="562" width="432" height="66" rx="8" fill="#fff0cf"/><text x="40" y="589" font-weight="600">Accepted ≠ delivered.</text><text x="40" y="614" font-size="16">Retries need a duplicate-send policy.</text>
|
|
18
|
+
</g>
|
|
19
|
+
</svg>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-email",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "0.1.0",
|
|
4
4
|
"description": "AntelopeJS interface for sending email: single, batch and template messages with attachments",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -35,21 +35,31 @@
|
|
|
35
35
|
"provenance": true
|
|
36
36
|
},
|
|
37
37
|
"scripts": {
|
|
38
|
-
"build": "rimraf dist && tsc",
|
|
38
|
+
"build": "rimraf dist && tsc -p tsconfig.build.json",
|
|
39
39
|
"format": "oxfmt .",
|
|
40
40
|
"lint:fix": "oxlint --fix",
|
|
41
41
|
"lint": "oxlint",
|
|
42
42
|
"prepack": "pnpm run build",
|
|
43
43
|
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
44
44
|
"format:check": "oxfmt --check .",
|
|
45
|
-
"knip": "knip"
|
|
45
|
+
"knip": "knip",
|
|
46
|
+
"prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
|
|
47
|
+
"checks": "antelopejs-checks",
|
|
48
|
+
"size": "antelopejs-check-size",
|
|
49
|
+
"sync": "antelopejs-sync",
|
|
50
|
+
"sync:check": "antelopejs-sync --check",
|
|
51
|
+
"typecheck": "tsc --noEmit",
|
|
52
|
+
"test": "pnpm run build",
|
|
53
|
+
"suppressions": "antelopejs-suppressions",
|
|
54
|
+
"suppressions:update": "antelopejs-suppressions --update"
|
|
46
55
|
},
|
|
47
56
|
"devDependencies": {
|
|
48
57
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
49
|
-
"@antelopejs/tooling-configs": "^0.
|
|
58
|
+
"@antelopejs/tooling-configs": "^0.2.11",
|
|
50
59
|
"@types/node": "^22.19.15",
|
|
51
60
|
"eslint-plugin-perfectionist": "^5.11.0",
|
|
52
61
|
"knip": "^6.34.0",
|
|
62
|
+
"lefthook": "^2.2.2",
|
|
53
63
|
"oxfmt": "^0.66.0",
|
|
54
64
|
"oxlint": "1.81.0",
|
|
55
65
|
"oxlint-tsgolint": "^7.0.2001",
|
|
@@ -56,7 +56,7 @@ if (!response.success) {
|
|
|
56
56
|
}
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
`SendTemplate` takes `template: { id }` (provider-hosted) or `{ content, type }` (inline) plus `variables` / `recipientVariables`. `SendBatch` takes `{ messages, defaults?, continueOnError? }` and returns per-message results.
|
|
59
|
+
`SendTemplate` takes `template: { id }` (provider-hosted) or `{ content, type }` (inline) plus `variables` / `recipientVariables`. These and `providerOptions` are typed `JsonObject` (exported with `JsonValue`): strings, numbers, booleans, `null`, arrays and objects of them, with `undefined` accepted as a key's value. Convert a `Date` or `Buffer` first; an object typed as an `interface` is rejected, so use a `type` alias or spread it into a literal. `SendBatch` takes `{ messages, defaults?, continueOnError? }` and returns per-message results.
|
|
60
60
|
|
|
61
61
|
## Providing
|
|
62
62
|
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"cases": [
|
|
4
|
+
{
|
|
5
|
+
"id": "email-interface-send-attachment",
|
|
6
|
+
"area": "framework",
|
|
7
|
+
"style": "clean",
|
|
8
|
+
"prompt": "In my AntelopeJS module, how do I send an HTML email with a PDF attached?",
|
|
9
|
+
"expect": {
|
|
10
|
+
"skills": ["email-interface"],
|
|
11
|
+
"acceptable": ["antelopejs", "ajs-consume-interface"],
|
|
12
|
+
"mustMention": ["Send", "attachments"]
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"id": "email-interface-batch-casual",
|
|
17
|
+
"area": "framework",
|
|
18
|
+
"style": "casual",
|
|
19
|
+
"prompt": "need to fire off a bunch of emails at once from my module, which call do i use",
|
|
20
|
+
"expect": {
|
|
21
|
+
"skills": ["email-interface"],
|
|
22
|
+
"acceptable": ["antelopejs", "ajs-consume-interface"],
|
|
23
|
+
"mustMention": ["SendBatch"]
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"id": "email-interface-template-variables",
|
|
28
|
+
"area": "framework",
|
|
29
|
+
"style": "clean",
|
|
30
|
+
"prompt": "I want to send a templated email with per-recipient values through the AntelopeJS email interface. What do I pass?",
|
|
31
|
+
"expect": {
|
|
32
|
+
"skills": ["email-interface"],
|
|
33
|
+
"acceptable": ["antelopejs", "ajs-consume-interface"],
|
|
34
|
+
"mustMention": ["SendTemplate", "recipientVariables"]
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"id": "email-interface-dms-mailing-neighbour",
|
|
39
|
+
"area": "modules",
|
|
40
|
+
"style": "clean",
|
|
41
|
+
"prompt": "How do I ship email templates and template categories as code in a DMS module?",
|
|
42
|
+
"expect": {
|
|
43
|
+
"skills": ["dms-mailing"],
|
|
44
|
+
"acceptable": ["dms", "antelopejs"],
|
|
45
|
+
"avoid": ["email-interface"]
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
]
|
|
49
|
+
}
|