@antelopejs/interface-email 0.1.1 → 0.2.1
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 +29 -6
- package/dist/index.d.ts +3 -0
- package/dist/index.js.map +1 -1
- package/docs/1.introduction.md +14 -13
- package/docs/2.sending-emails.md +1 -1
- package/package.json +7 -7
- package/skills/email-interface/SKILL.md +2 -1
package/README.md
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
|
-
|
|
1
|
+
<a href="https://github.com/AntelopeJS/antelopejs"><img data-illustration src="./.github/readme/strip.svg" width="100%" alt="INTERFACE · EMAIL: part of AntelopeJS, hexagonal architecture beyond your own code. A glowing button reads Star AntelopeJS."></a>
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
<a href="./docs/1.introduction.md"><img data-illustration alt="
|
|
4
|
+
|
|
5
|
+
# `@antelopejs/interface-email`
|
|
6
|
+
|
|
7
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-email"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-email?style=for-the-badge&labelColor=000000&color=000000"></a> <a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-email?style=for-the-badge&labelColor=000000&color=000000"></a> <a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a> <a href="./docs/1.introduction.md"><img data-illustration alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a> <a href="https://github.com/AntelopeJS/antelopejs"><img data-illustration alt="Star AntelopeJS" src="https://img.shields.io/github/stars/AntelopeJS/antelopejs?label=Star%20AntelopeJS&style=for-the-badge&labelColor=000000&color=000000&logo=github"></a>
|
|
8
|
+
|
|
9
|
+
**The AntelopeJS contract for email. Send templated, batch and attachment emails without naming a provider.**
|
|
10
|
+
|
|
11
|
+
[Documentation](./docs/1.introduction.md) · [Implementations](#implementations) · [All interfaces and providers](https://github.com/AntelopeJS/antelopejs#ecosystem)
|
|
12
|
+
|
|
8
13
|
</div>
|
|
9
14
|
|
|
10
15
|
The AntelopeJS contract for sending email: one API for single, batch and template messages, whatever provider delivers them.
|
|
@@ -70,7 +75,7 @@ export async function sendWelcome(address: string) {
|
|
|
70
75
|
|
|
71
76
|
| Package | Supported | Tested with |
|
|
72
77
|
| ---------------------------- | ---------------- | ----------- |
|
|
73
|
-
| `@antelopejs/interface-core` | `>=0.
|
|
78
|
+
| `@antelopejs/interface-core` | `>=0.5.1 <0.6.0` | `0.5.1` |
|
|
74
79
|
|
|
75
80
|
<!-- antelopejs-docs-compat:end -->
|
|
76
81
|
|
|
@@ -87,6 +92,24 @@ pnpm lint
|
|
|
87
92
|
pnpm build
|
|
88
93
|
```
|
|
89
94
|
|
|
95
|
+
## Part of AntelopeJS
|
|
96
|
+
|
|
97
|
+
This package belongs to [AntelopeJS](https://github.com/AntelopeJS/antelopejs), the TypeScript framework where modules depend on contracts and the application chooses the provider. The open-source back office [AntelopeJS DMS](https://github.com/AntelopeJS/dms) is built on it.
|
|
98
|
+
|
|
99
|
+
<!-- antelopejs-framework-modules:start -->
|
|
100
|
+
|
|
101
|
+
| Area | Contracts | Providers |
|
|
102
|
+
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
103
|
+
| API | [`interface-api`](https://github.com/AntelopeJS/interface-api) · [`interface-api-util`](https://github.com/AntelopeJS/interface-api-util) · [`interface-data-api`](https://github.com/AntelopeJS/interface-data-api) | [`api`](https://github.com/AntelopeJS/api) |
|
|
104
|
+
| Auth | [`interface-auth`](https://github.com/AntelopeJS/interface-auth) | [`auth-jwt`](https://github.com/AntelopeJS/auth-jwt) |
|
|
105
|
+
| Database | [`interface-database`](https://github.com/AntelopeJS/interface-database) · [`interface-database-decorators`](https://github.com/AntelopeJS/interface-database-decorators) · [`interface-database-catalog`](https://github.com/AntelopeJS/interface-database-catalog) · [`interface-mongodb`](https://github.com/AntelopeJS/interface-mongodb) · [`interface-rethinkdb`](https://github.com/AntelopeJS/interface-rethinkdb) | [`postgres`](https://github.com/AntelopeJS/postgres) · [`mysql`](https://github.com/AntelopeJS/mysql) · [`mongodb`](https://github.com/AntelopeJS/mongodb) · [`rethinkdb`](https://github.com/AntelopeJS/rethinkdb) |
|
|
106
|
+
| Redis | [`interface-redis`](https://github.com/AntelopeJS/interface-redis) · [`interface-redis-scheduler`](https://github.com/AntelopeJS/interface-redis-scheduler) | [`redis`](https://github.com/AntelopeJS/redis) |
|
|
107
|
+
| Email | **`interface-email`** | [`nodemailer`](https://github.com/AntelopeJS/nodemailer) · [`brevo`](https://github.com/AntelopeJS/brevo) |
|
|
108
|
+
| File storage | [`interface-file-storage`](https://github.com/AntelopeJS/interface-file-storage) | [`file-storage-local`](https://github.com/AntelopeJS/file-storage-local) · [`file-storage-s3`](https://github.com/AntelopeJS/file-storage-s3) |
|
|
109
|
+
| Payments | [`interface-payment`](https://github.com/AntelopeJS/interface-payment) · [`interface-subscriptions`](https://github.com/AntelopeJS/interface-subscriptions) · [`interface-stripe`](https://github.com/AntelopeJS/interface-stripe) | [`stripe`](https://github.com/AntelopeJS/stripe) · [`mollie`](https://github.com/AntelopeJS/mollie) · [`checkout-com`](https://github.com/AntelopeJS/checkout-com) · [`payment-subscriptions`](https://github.com/AntelopeJS/payment-subscriptions) |
|
|
110
|
+
|
|
111
|
+
<!-- antelopejs-framework-modules:end -->
|
|
112
|
+
|
|
90
113
|
## License
|
|
91
114
|
|
|
92
115
|
[Apache-2.0](./LICENSE)
|
package/dist/index.d.ts
CHANGED
|
@@ -200,7 +200,10 @@ export interface BatchEmailResponse {
|
|
|
200
200
|
/** Supported features of the email provider */
|
|
201
201
|
export interface ProviderFeatures {
|
|
202
202
|
batch: boolean;
|
|
203
|
+
/** SendTemplate works for at least inline templates */
|
|
203
204
|
templates: boolean;
|
|
205
|
+
/** SendTemplate accepts a ProviderTemplate (a template stored by the provider, named by id) */
|
|
206
|
+
providerTemplates: boolean;
|
|
204
207
|
scheduling: boolean;
|
|
205
208
|
openTracking: boolean;
|
|
206
209
|
clickTracking: boolean;
|
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;AAqS/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
|
@@ -107,19 +107,20 @@ console.log(capabilities.maxRecipients); // undefined when the provider reports
|
|
|
107
107
|
|
|
108
108
|
The `ProviderFeatures` object has these flags:
|
|
109
109
|
|
|
110
|
-
| Feature | Description
|
|
111
|
-
| ------------------- |
|
|
112
|
-
| `batch` | Supports sending multiple emails in one request
|
|
113
|
-
| `templates` |
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
|
|
122
|
-
|
|
110
|
+
| Feature | Description |
|
|
111
|
+
| ------------------- | -------------------------------------------------------------------------------------------- |
|
|
112
|
+
| `batch` | Supports sending multiple emails in one request |
|
|
113
|
+
| `templates` | `SendTemplate` works for at least inline templates |
|
|
114
|
+
| `providerTemplates` | `SendTemplate` accepts a `ProviderTemplate` (a template stored by the provider, named by id) |
|
|
115
|
+
| `scheduling` | Supports delayed email delivery |
|
|
116
|
+
| `openTracking` | Tracks when recipients open emails |
|
|
117
|
+
| `clickTracking` | Tracks when recipients click links |
|
|
118
|
+
| `inlineAttachments` | Supports inline, embedded images |
|
|
119
|
+
| `tags` | Supports email tagging for analytics |
|
|
120
|
+
| `metadata` | Supports custom metadata on emails |
|
|
121
|
+
| `priority` | Supports email priority levels |
|
|
122
|
+
|
|
123
|
+
Check `providerTemplates` before you pass a `ProviderTemplate`: `templates` alone promises only inline templates. A provider built before this flag omits it, so treat a missing `providerTemplates` as `false`. `@antelopejs/nodemailer` releases that predate the flag set `templates` to `true`, render inline templates only, and answer a provider-hosted template with an unsuccessful response ([AntelopeJS/nodemailer#45](https://github.com/AntelopeJS/nodemailer/issues/45)). A flag is the module's own claim. `@antelopejs/brevo` reports `openTracking`, `clickTracking` and `inlineAttachments` as `true` but applies none of them ([AntelopeJS/brevo#44](https://github.com/AntelopeJS/brevo/issues/44)).
|
|
123
124
|
|
|
124
125
|
Each implementing module decides which fields it applies. A module can drop a field that it does not apply and still report the send as successful. To keep your code portable, check the capabilities before you use an optional feature:
|
|
125
126
|
|
package/docs/2.sending-emails.md
CHANGED
|
@@ -202,7 +202,7 @@ The `SendTemplate` function renders an email from a template before it sends. A
|
|
|
202
202
|
|
|
203
203
|
### Provider-hosted templates
|
|
204
204
|
|
|
205
|
-
A `ProviderTemplate` names a template stored in the provider's system by its ID. The ID format is provider behaviour. `@antelopejs/brevo` expects a numeric ID, and `@antelopejs/nodemailer` does not support provider-hosted templates.
|
|
205
|
+
A `ProviderTemplate` names a template stored in the provider's system by its ID. The ID format is provider behaviour. `@antelopejs/brevo` expects a numeric ID, and `@antelopejs/nodemailer` does not support provider-hosted templates. Check `capabilities.features.providerTemplates` before you send one.
|
|
206
206
|
|
|
207
207
|
```ts
|
|
208
208
|
import { SendTemplate } from "@antelopejs/interface-email";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-email",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "AntelopeJS interface for sending email: single, batch and template messages with attachments",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -40,10 +40,10 @@
|
|
|
40
40
|
"lint:fix": "oxlint --fix",
|
|
41
41
|
"lint": "oxlint",
|
|
42
42
|
"prepack": "pnpm run build",
|
|
43
|
-
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
43
|
+
"release": "pnpm run lint && pnpm run typecheck && pnpm run prepack && release-it",
|
|
44
44
|
"format:check": "oxfmt --check .",
|
|
45
45
|
"knip": "knip",
|
|
46
|
-
"prepare": "if
|
|
46
|
+
"prepare": "if [ -e .git ] && command -v git >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1 && GIT_DIR=.git GIT_WORK_TREE=. git rev-parse --git-dir >/dev/null 2>&1; then GIT_DIR=.git GIT_WORK_TREE=. lefthook install; fi",
|
|
47
47
|
"checks": "antelopejs-checks",
|
|
48
48
|
"size": "antelopejs-check-size",
|
|
49
49
|
"sync": "antelopejs-sync",
|
|
@@ -54,9 +54,9 @@
|
|
|
54
54
|
"suppressions:update": "antelopejs-suppressions --update"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
|
-
"@antelopejs/core": "
|
|
58
|
-
"@antelopejs/interface-core": ">=0.
|
|
59
|
-
"@antelopejs/tooling-configs": "
|
|
57
|
+
"@antelopejs/core": "~1.23.0",
|
|
58
|
+
"@antelopejs/interface-core": ">=0.5.1 <0.6.0",
|
|
59
|
+
"@antelopejs/tooling-configs": ">=0.6.0 <0.7.0",
|
|
60
60
|
"@types/node": "^22.19.15",
|
|
61
61
|
"eslint-plugin-perfectionist": "^5.11.0",
|
|
62
62
|
"knip": "^6.34.0",
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
"typescript": "^5.9.3"
|
|
71
71
|
},
|
|
72
72
|
"peerDependencies": {
|
|
73
|
-
"@antelopejs/interface-core": ">=0.
|
|
73
|
+
"@antelopejs/interface-core": ">=0.5.1 <0.6.0"
|
|
74
74
|
},
|
|
75
75
|
"packageManager": "pnpm@10.6.5",
|
|
76
76
|
"antelopeJs": {
|
|
@@ -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`. 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.
|
|
59
|
+
`SendTemplate` takes `template: { id }` (provider-hosted, gated on `features.providerTemplates`) or `{ content, type }` (inline, gated on `features.templates`) 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
|
|
|
@@ -81,6 +81,7 @@ ImplementInterface(EmailInterface, {
|
|
|
81
81
|
features: {
|
|
82
82
|
batch: true,
|
|
83
83
|
templates: false,
|
|
84
|
+
providerTemplates: false,
|
|
84
85
|
scheduling: false,
|
|
85
86
|
openTracking: false,
|
|
86
87
|
clickTracking: false,
|