@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 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?: Record<string, unknown>;
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?: Record<string, unknown>;
124
+ variables?: JsonObject;
109
125
  /** Per-recipient variables (keyed by email address) */
110
- recipientVariables?: Record<string, Record<string, unknown>>;
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?: Record<string, unknown>;
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;AAgT/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"}
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"}
@@ -1,6 +1,20 @@
1
1
  # Introduction
2
2
 
3
- The `@antelopejs/interface-email` package defines a provider-agnostic email interface for AntelopeJS applications. It exposes a consistent API for sending emails regardless of the underlying provider (SendGrid, Mailgun, Amazon SES, etc.).
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
+ ![Choose a sending API, then inspect the provider response; acceptance does not prove inbox delivery.](./assets/message-lifecycle.svg){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
- Each function returns a typed response that includes delivery status, provider message IDs, and error details when applicable.
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 { GetCapabilities, Send } from "@antelopejs/interface-email";
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: any = {
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("2026-04-01T09:00:00Z") };
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.
@@ -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`. Including both ensures compatibility with all email clients.
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 controls the email's delivery priority. It accepts one of three values:
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"` | Urgent emails that should be delivered immediately |
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("2026-04-06T08:45:00"),
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>Invoice #001 attached.</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>Invoice #002 attached.</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 contains an `EmailError` object:
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
- // Safe to retry this request
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.
@@ -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
- ## The `BaseAttachment` Interface
5
+ ## Choose the source of the bytes
6
6
 
7
- Every attachment type extends `BaseAttachment`, which defines shared metadata fields:
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
- | Field | Type | Required | Description |
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 pdfBuffer = Buffer.from(/* generated PDF data */);
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.pdf",
29
- contentType: "application/pdf",
30
- content: pdfBuffer,
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: "logo.png",
50
- contentType: "image/png",
51
- content: "iVBORw0KGgoAAAANSUhEUgAA...",
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: "Brand Assets",
58
- text: "Logo attached.",
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 { Send, BufferAttachment } from "@antelopejs/interface-email";
115
+ import { readFile } from "node:fs/promises";
116
+ import { Send } from "@antelopejs/interface-email";
111
117
 
112
- const logoBuffer = Buffer.from(/* logo image data */);
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.6",
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.0.9",
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
+ }