@antelopejs/interface-dms-mailing 0.8.0 → 0.9.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/README.md CHANGED
@@ -15,7 +15,7 @@ The AntelopeJS interface to send DMS mailing templates and report e-mail events
15
15
 
16
16
  - Sends a published template by its slug, to one recipient or many, in a given locale and with its variables (`SendTemplate`).
17
17
  - Reports a provider event (delivered, opened, clicked, bounced…) against the send it belongs to (`RecordEmailEvent`).
18
- - Ships templates and template categories as code, published and idempotent, without overwriting what a user changed since (`DeclareTemplate`, `DeclareTemplateCategory`).
18
+ - Ships templates and template categories as code, published and idempotent, without overwriting what a user changed since (`DeclareTemplate`, `DeclareTemplateCategory`), and writes the workspace sender when a workspace is provisioned (`DeclareSender`).
19
19
  - Imports past sends and their events with their own dates, for a demo data set or a move from another provider (`ImportSends`).
20
20
  - Exports the template and send types (`Block`, `TemplateContent`, `VariableDefinition`, `SendStatus`, `EmailEvent`…) for code that builds or inspects templates.
21
21
  - Keeps your module independent of the implementation, [`@antelopejs/dms-mailing`](https://www.npmjs.com/package/@antelopejs/dms-mailing).
@@ -53,7 +53,7 @@ A recipient on the workspace's suppression list gets no e-mail: its result has t
53
53
 
54
54
  ## Compatibility
55
55
 
56
- The implementation is `@antelopejs/dms-mailing >=0.5.0`; `DeclareTemplate`, `DeclareTemplateCategory` and `ImportSends` need the first release implementing interface 0.8, which depends on `>=0.8.0 <0.9.0`. The interface declares these dependencies:
56
+ Interface 0.8 requires `@antelopejs/dms-mailing >=0.6.0`, whose interface dependency is `>=0.8.0 <0.9.0`. This includes `DeclareTemplate`, `DeclareTemplateCategory` and `ImportSends`, all requiring an explicit `tenantId`. Mailing 0.5 remains on interface 0.7. `DeclareSender` needs interface 0.9 and the first release implementing it (`>=0.9.0 <0.10.0`). The interface declares these dependencies:
57
57
 
58
58
  <!-- docs-compat: ./package.json#dependencies -->
59
59
 
package/dist/index.d.ts CHANGED
@@ -106,10 +106,12 @@ export type SendEventType = "queued" | "sent" | "delivered" | "opened" | "clicke
106
106
  export type SendStatus = SendEventType | "suppressed";
107
107
  export declare const SendTemplate: (slug: string, params: SendTemplateParams) => Promise<SendTemplateResult>;
108
108
  export declare const RecordEmailEvent: (tenantId: string, event: EmailEvent) => Promise<boolean>;
109
+ export declare const LOCALIZED_TEXT_FALLBACK_LOCALE = "en";
110
+ export type LocalizedText = Record<string, string>;
109
111
  export interface TemplateDeclaration {
110
112
  tenantId: string;
111
113
  slug: string;
112
- name: string;
114
+ name: LocalizedText;
113
115
  category?: string;
114
116
  content: TemplateContent;
115
117
  variables?: VariableDefinition[];
@@ -126,13 +128,19 @@ export interface DeclareTemplateResult {
126
128
  export interface TemplateCategoryDeclaration {
127
129
  tenantId: string;
128
130
  id: string;
129
- label: string;
131
+ label: LocalizedText;
130
132
  icon: string;
131
133
  }
132
134
  export interface DeclareTemplateCategoryResult {
133
135
  id: string;
134
136
  outcome: DeclarationOutcome;
135
137
  }
138
+ export interface SenderDeclaration {
139
+ tenantId: string;
140
+ email: string;
141
+ name?: string;
142
+ replyTo?: string;
143
+ }
136
144
  export interface ImportedSendEvent {
137
145
  type: SendEventType;
138
146
  at: Date;
@@ -162,4 +170,5 @@ export interface ImportSendsResult {
162
170
  }
163
171
  export declare const DeclareTemplate: (declaration: TemplateDeclaration) => Promise<DeclareTemplateResult>;
164
172
  export declare const DeclareTemplateCategory: (declaration: TemplateCategoryDeclaration) => Promise<DeclareTemplateCategoryResult>;
173
+ export declare const DeclareSender: (declaration: SenderDeclaration) => Promise<void>;
165
174
  export declare const ImportSends: (params: SendImport) => Promise<ImportSendsResult>;
package/dist/index.js CHANGED
@@ -1,9 +1,11 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.ImportSends = exports.DeclareTemplateCategory = exports.DeclareTemplate = exports.RecordEmailEvent = exports.SendTemplate = void 0;
3
+ exports.ImportSends = exports.DeclareSender = exports.DeclareTemplateCategory = exports.DeclareTemplate = exports.LOCALIZED_TEXT_FALLBACK_LOCALE = exports.RecordEmailEvent = exports.SendTemplate = void 0;
4
4
  const interface_core_1 = require("@antelopejs/interface-core");
5
5
  exports.SendTemplate = (0, interface_core_1.InterfaceFunction)();
6
6
  exports.RecordEmailEvent = (0, interface_core_1.InterfaceFunction)();
7
+ exports.LOCALIZED_TEXT_FALLBACK_LOCALE = "en";
7
8
  exports.DeclareTemplate = (0, interface_core_1.InterfaceFunction)();
8
9
  exports.DeclareTemplateCategory = (0, interface_core_1.InterfaceFunction)();
10
+ exports.DeclareSender = (0, interface_core_1.InterfaceFunction)();
9
11
  exports.ImportSends = (0, interface_core_1.InterfaceFunction)();
package/docs/1.index.md CHANGED
@@ -5,9 +5,35 @@ description: Consumer contract for sending templates and recording provider even
5
5
 
6
6
  # Mailing interface
7
7
 
8
- `@antelopejs/interface-dms-mailing` exposes five backend functions and the template types below: two to send and to report events, two to ship templates and categories as code, and one to import past sends. Load `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider before calling them. Import from the interface package, not the runtime module's services.
8
+ `@antelopejs/interface-dms-mailing` exposes six backend functions and the template types below: two to send and to report events, three to ship templates, categories and the sender as code, and one to import past sends. Load `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider before calling them. Import from the interface package, not the runtime module's services.
9
9
 
10
- All five functions take an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints: authenticate and authorize the tenant in the calling module. A missing implementation or a storage failure can reject the promise.
10
+ All six functions take an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints: authenticate and authorize the tenant in the calling module. A missing implementation or a storage failure can reject the promise.
11
+
12
+ ## Consume per-recipient results
13
+
14
+ Publish an `order-confirmation` template in your authorized tenant, with
15
+ `order.total` as a variable. This example performs a real send; use an inbox you
16
+ control and supply any additional variables required by your template.
17
+
18
+ ```ts docs-check
19
+ import { SendTemplate } from "@antelopejs/interface-dms-mailing";
20
+
21
+ export async function sendOrderConfirmation(tenantId: string, recipients: string[]) {
22
+ const result = await SendTemplate("order-confirmation", {
23
+ tenantId,
24
+ to: recipients,
25
+ variables: { order: { total: "48.00" } },
26
+ source: "checkout",
27
+ });
28
+ return result.results ?? [result];
29
+ }
30
+ ```
31
+
32
+ The returned array lets you inspect each recipient separately. For example, a
33
+ two-recipient call can return `sent` for one address and `suppressed` for the
34
+ other. Do not resend both: the first email may already be on its way, and the
35
+ suppressed recipient must not be retried. The **Sends** page records the template
36
+ version and locale; provider events later add delivery information.
11
37
 
12
38
  ## SendTemplate
13
39
 
@@ -58,25 +84,6 @@ Provider failures become failed recipient results. If recording a send fails, th
58
84
 
59
85
  Validation failures reject instead of returning recipient results. The runtime's errors carry codes `no_recipient`, `template_not_found`, `template_not_live`, `invalid_content`, or `missing_variables`; the error class is not an interface export. Missing-variable refusal follows the workspace setting. Marketing footer URLs are required system variables when the template uses them; test sends do not require those system URLs. Storage or downstream notification failures can also reject after side effects have started, so this call is not transactional or idempotent.
60
86
 
61
- ### Consume per-recipient results
62
-
63
- This example returns the outcomes for an authorized tenant; the caller decides
64
- whether a failed recipient can be retried without duplicating delivery.
65
-
66
- ```ts docs-check
67
- import { SendTemplate } from "@antelopejs/interface-dms-mailing";
68
-
69
- export async function sendOrderConfirmation(tenantId: string, recipients: string[]) {
70
- const result = await SendTemplate("order-confirmation", {
71
- tenantId,
72
- to: recipients,
73
- variables: { order: { total: "48.00" } },
74
- source: "checkout",
75
- });
76
- return result.results ?? [result];
77
- }
78
- ```
79
-
80
87
  ## RecordEmailEvent
81
88
 
82
89
  ```ts [Contract]
@@ -103,7 +110,7 @@ declare function RecordEmailEvent(
103
110
 
104
111
  The call returns `true` when it records the event. It returns `false` for an unmatched message, a duplicate event, or a send that is retiring or no longer accepts events. Supply a stable `details.eventId` for provider retries. Without it, deduplication requires the same explicit `at`, event type, and serialized details; omitting both event ID and timestamp does not deduplicate retries.
105
112
 
106
- Accepted events update the send timeline, status and engagement counters, publish realtime and automation events, and can notify tenant owners of template problems. A hard bounce, spam complaint, or unsubscribe suppresses the recipient; soft bounces and test sends do not. Suppression-write failures are logged without rejecting the recorded event. Repeated activity conflicts, storage failures, or downstream publication failures can reject; a rejection does not guarantee that no event was stored.
113
+ Accepted events update the send timeline, status and engagement counters, publish realtime and automation events, and can notify tenant owners of template problems. A hard bounce, spam complaint, or unsubscribe suppresses the recipient. A test send suppresses only on a hard bounce; soft bounces never suppress. Suppression-write failures are logged without rejecting the recorded event. Repeated activity conflicts, storage failures, or downstream publication failures can reject; a rejection does not guarantee that no event was stored.
107
114
 
108
115
  `details.reason` supplies provider error text. `details.bounceType` distinguishes `soft`/`transient`/`temporary` from `hard`/`permanent`; otherwise the SMTP class in the reason decides. `details.url` and `details.userAgent` annotate engagement events. Authenticate a provider's webhook before translating it to this trusted call. The [runtime webhook guide](/docs/modules/mailing/extending#webhook-contract) defines HTTP authentication and response bodies.
109
116
 
@@ -111,12 +118,17 @@ Accepted events update the send timeline, status and engagement counters, publis
111
118
 
112
119
  A project can declare its transactional templates from backend code instead of creating them in the dashboard. A newly created template claims its slug, is published as v1 with history, and is ready for `SendTemplate` when the call resolves. Existing templates remain subject to the ownership and lifecycle rules below: `unchanged` and `kept` do not guarantee that an archived or unpublished template is sendable.
113
120
 
114
- `DeclareTemplate`, `DeclareTemplateCategory` and `ImportSends` require an explicit `tenantId`, in TypeScript and at runtime. Omission, an empty string or whitespace-only input rejects before any write, with `invalid_template`, `invalid_category` or `invalid_import` respectively and `tenantId` in the message. There is no default fallback. Passing `DEFAULT_TENANT_ID` explicitly remains valid. This requirement identifies the target; it proves neither authorization nor completed provisioning. Trusted application code must enforce both. Existing `SendTemplate` and `RecordEmailEvent` contracts are unchanged.
121
+ `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `ImportSends` require an explicit `tenantId`, in TypeScript and at runtime. Omission, an empty string or whitespace-only input rejects before any write, with `invalid_template`, `invalid_category`, `invalid_sender` or `invalid_import` respectively and `tenantId` in the message. There is no default fallback. Passing `DEFAULT_TENANT_ID` explicitly remains valid. This requirement identifies the target; it proves neither authorization nor completed provisioning. Trusted application code must enforce both. Existing `SendTemplate` and `RecordEmailEvent` contracts are unchanged.
122
+
123
+ ### Names and labels in several languages
124
+
125
+ A template's `name` and a category's `label` are `LocalizedText`: one text per language, `{ en: "Welcome", fr: "Bienvenue" }`. The `en` text is required (`LOCALIZED_TEXT_FALLBACK_LOCALE`): a reader whose language has no text reads it. They are stored as localized fields (`@Localized`), so the dashboard shows, searches and sorts each user's own language, sent by the DMS frontend in `x-content-language`. Do not pass `$` i18n keys: a name is content, not a translation key. A user renaming a template in the dashboard writes the language they work in, which counts as a change (`kept`).
115
126
 
116
127
  ### DeclareTemplate
117
128
 
118
129
  ```ts [Contract]
119
130
  import type {
131
+ LocalizedText, // Record<string, string>
120
132
  TemplateContent,
121
133
  VariableDefinition,
122
134
  } from "@antelopejs/interface-dms-mailing";
@@ -124,7 +136,7 @@ import type {
124
136
  interface TemplateDeclaration {
125
137
  tenantId: string; // explicit authorized workspace, non-blank
126
138
  slug: string;
127
- name: string;
139
+ name: LocalizedText; // { en: "…", fr: "…" }, en required
128
140
  category?: string; // a category id of the workspace settings
129
141
  content: TemplateContent;
130
142
  variables?: VariableDefinition[];
@@ -169,7 +181,7 @@ A storage or attention-refresh failure can reject after publication commits. The
169
181
  interface TemplateCategoryDeclaration {
170
182
  tenantId: string;
171
183
  id: string; // lowercase letters, digits and dashes
172
- label: string;
184
+ label: LocalizedText; // { en: "…", fr: "…" }, en required
173
185
  icon: string; // a Phosphor icon, such as "i-ph-repeat"
174
186
  }
175
187
 
@@ -185,6 +197,21 @@ declare function DeclareTemplateCategory(
185
197
 
186
198
  Adds a category to the workspace settings (`created`), relabels one still as last declared (`updated`), or does nothing (`unchanged`). A category a user relabelled or removed since, and one that existed before any declaration (the defaults `orders`, `account`, `billing`, `marketing` and `forms` among them), is left as it is (`kept`): a removed category is never added back. A label another category already has rejects with `invalid_category`. Declarations of one workspace run one after the other within one process; this queue is not a cross-process lock and does not serialize dashboard settings writes. Coordinate concurrent category/settings writers externally. Declare a category before templates that name it.
187
199
 
200
+ ### DeclareSender
201
+
202
+ ```ts [Contract]
203
+ interface SenderDeclaration {
204
+ tenantId: string;
205
+ email: string; // the address e-mails are sent from
206
+ name?: string; // shown next to it
207
+ replyTo?: string; // replies go to the sender address when absent
208
+ }
209
+
210
+ declare function DeclareSender(declaration: SenderDeclaration): Promise<void>;
211
+ ```
212
+
213
+ Writes the Sender section of the workspace settings, so a fresh workspace sends from the project's address instead of the provider's default (and the Overview does not ask for one). It is a plain write: the declared name, address and reply-to replace the stored ones, and an absent `name` or `replyTo` clears it. Call it once, when the project provisions the workspace (`Hook.TENANT_BEING_PROVISIONED`), not on every boot: from then on the settings are the user's, and a later call would overwrite their changes. The address and the reply-to follow the settings form's rules (an internationalized domain is stored in its ASCII form), and a missing or invalid address rejects with `invalid_sender`, naming the field. It rewrites the whole settings row, like `DeclareTemplateCategory`: await one before calling the other for the same workspace.
214
+
188
215
  ### When to call
189
216
 
190
217
  The calls wait for the module and for the DMS database, so start order never makes them fail: a call made before `@antelopejs/dms-mailing` is constructed is queued by the interface, and a call made before the DMS opened its database waits for it. The DMS opens it in its own `start()`, after every module's `construct()`, so:
@@ -202,11 +229,11 @@ import {
202
229
  } from "@antelopejs/interface-dms-mailing";
203
230
 
204
231
  export async function declareMailingContent(tenantId: string): Promise<void> {
205
- await DeclareTemplateCategory({ tenantId, id: "subscriptions", label: "Subscriptions", icon: "i-ph-repeat" });
232
+ await DeclareTemplateCategory({ tenantId, id: "subscriptions", label: { en: "Subscriptions", fr: "Abonnements" }, icon: "i-ph-repeat" });
206
233
  const result = await DeclareTemplate({
207
234
  tenantId,
208
235
  slug: "subscription-renewed",
209
- name: "Subscription renewed",
236
+ name: { en: "Subscription renewed", fr: "Abonnement renouvelé" },
210
237
  category: "subscriptions",
211
238
  content: {
212
239
  locales: {
@@ -340,4 +367,6 @@ All blocks share `BlockBase`: `id: string`, the discriminant `type: BlockType`,
340
367
 
341
368
  `Condition` has `path: string`, `operator: ConditionOperator`, and `value: string`. Operators are `truthy`, `falsy`, `eq`, `ne`, `gt`, and `lt`. `VariableDefinition` has `path: string`, `type: VariableType`, and `required: boolean`. Variable types are `string`, `text`, `number`, `money`, `date`, `url`, `boolean`, and `array`.
342
369
 
370
+ Values are written in the locale the e-mail is rendered in. A money value `{ value, currency }` (the amount in the currency's minor unit, an ISO 4217 code: `{ value: 987420, currency: "EUR" }` reads "€9,874.20" in English, "9 874,20 €" in French) and a `Date` (a long date, in the server's time zone) are formatted wherever they appear, list rows included. An ISO 8601 string is written as a date only at a path the template declares `date`: a day (`2026-11-14`) as that calendar day, a moment as its day in the server's time zone. Other values, strings the caller already formatted among them and numbers, are written as given.
371
+
343
372
  For template setup, footer variables and automation integration, use the [extending guide](/docs/modules/mailing/extending). Installation, configuration and HTTP routes remain in the runtime guide.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-dms-mailing",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "AntelopeJS interface for the DMS mailing module: send templates and report e-mail events from any module.",
5
5
  "keywords": [
6
6
  "antelopejs",