@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 CHANGED
@@ -1,10 +1,15 @@
1
- # `@antelopejs/interface-email`
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
- <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>
5
- <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>
6
- <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>
7
- <a href="./docs/1.introduction.md"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
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.2.4 <1.0.0` | `0.2.4` |
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;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
+ {"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"}
@@ -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` | Supports `SendTemplate` |
114
- | `scheduling` | Supports delayed email delivery |
115
- | `openTracking` | Tracks when recipients open emails |
116
- | `clickTracking` | Tracks when recipients click links |
117
- | `inlineAttachments` | Supports inline, embedded images |
118
- | `tags` | Supports email tagging for analytics |
119
- | `metadata` | Supports custom metadata on emails |
120
- | `priority` | Supports email priority levels |
121
-
122
- The interface does not say which template kinds `templates` covers. `@antelopejs/nodemailer` sets it to `true` but renders inline templates only, and answers 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)).
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
 
@@ -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.1.1",
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 git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
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": "^1.16.0",
58
- "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
59
- "@antelopejs/tooling-configs": "^0.2.17",
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.2.4 <1.0.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,