@antelopejs/interface-dms-mailing 0.8.0 → 0.9.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 +2 -2
- package/dist/index.d.ts +12 -3
- package/dist/index.js +3 -1
- package/docs/1.index.md +71 -86
- package/package.json +2 -1
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
|
-
|
|
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,17 +106,19 @@ 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:
|
|
114
|
+
name: LocalizedText;
|
|
113
115
|
category?: string;
|
|
114
116
|
content: TemplateContent;
|
|
115
117
|
variables?: VariableDefinition[];
|
|
116
118
|
testData?: Record<string, unknown>;
|
|
117
119
|
author?: string;
|
|
118
120
|
}
|
|
119
|
-
export type DeclarationOutcome = "created" | "
|
|
121
|
+
export type DeclarationOutcome = "created" | "kept";
|
|
120
122
|
export interface DeclareTemplateResult {
|
|
121
123
|
templateId: string;
|
|
122
124
|
slug: string;
|
|
@@ -126,13 +128,19 @@ export interface DeclareTemplateResult {
|
|
|
126
128
|
export interface TemplateCategoryDeclaration {
|
|
127
129
|
tenantId: string;
|
|
128
130
|
id: string;
|
|
129
|
-
label:
|
|
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
|
|
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
|
|
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,20 +110,25 @@ 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
|
|
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
|
|
|
110
117
|
## Ship templates as code
|
|
111
118
|
|
|
112
|
-
A project can declare its transactional templates from backend code instead of creating them in the dashboard.
|
|
119
|
+
A project can declare its transactional templates from backend code instead of creating them in the dashboard. The content is written once, when the tenant is provisioned (see [When to call](#when-to-call)), and belongs to the tenant from then on: nothing replays it on a later boot. A newly created template claims its slug, is published as v1 with history, and is ready for `SendTemplate` when the call resolves.
|
|
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.
|
|
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:
|
|
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[];
|
|
@@ -132,7 +144,7 @@ interface TemplateDeclaration {
|
|
|
132
144
|
author?: string; // shown as "updated by" / "published by"; "system" when absent
|
|
133
145
|
}
|
|
134
146
|
|
|
135
|
-
type DeclarationOutcome = "created" | "
|
|
147
|
+
type DeclarationOutcome = "created" | "kept";
|
|
136
148
|
|
|
137
149
|
interface DeclareTemplateResult {
|
|
138
150
|
templateId: string;
|
|
@@ -146,22 +158,11 @@ declare function DeclareTemplate(
|
|
|
146
158
|
): Promise<DeclareTemplateResult>;
|
|
147
159
|
```
|
|
148
160
|
|
|
149
|
-
The slug is the key the caller chooses.
|
|
150
|
-
|
|
151
|
-
| The template under that slug | Outcome | What is written |
|
|
152
|
-
| --- | --- | --- |
|
|
153
|
-
| does not exist | `created` | the template, published as v1 |
|
|
154
|
-
| was declared with the same declaration | `unchanged` | no content or lifecycle change, whatever a user did since; interrupted history may be repaired |
|
|
155
|
-
| was declared before, is still `live` with no draft and holds exactly what the last declaration wrote | `updated` | the new declaration, published (a new version when content or variables changed) |
|
|
156
|
-
| was edited, holds a draft, was unpublished or archived since, or was made in the dashboard | `kept` | no content or lifecycle change; interrupted history may be repaired |
|
|
161
|
+
The slug is the key the caller chooses. A slug the tenant does not have yet is created and published as v1 (`created`). A slug it already has, declared before or made in the dashboard, is left as it is (`kept`): the call writes nothing, so a retried provisioning never creates a second template nor overwrites a user's work.
|
|
157
162
|
|
|
158
|
-
|
|
163
|
+
The declaration follows the dashboard's rules: the slug pattern and length of a new template, a non-blank name, content and variable declarations valid for the editor, at least one locale and a subject in every locale (what **Publish** requires). A creation also requires a category the workspace settings declare (or none). Validation errors use `invalid_template`, `unknown_category`, `nothing_to_publish` or `empty_subject`; their messages identify the invalid input, and they do not publish a template.
|
|
159
164
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
The declaration follows the dashboard's rules: the slug pattern and length of a new template, a non-blank name, content and variable declarations valid for the editor, at least one locale and a subject in every locale (what **Publish** requires). A creation or refresh also requires a category the workspace settings declare (or none); `unchanged` and `kept` do not fail merely because a user removed the original category. Validation errors use `invalid_template`, `unknown_category`, `nothing_to_publish` or `empty_subject`; their messages identify the invalid input, and they do not publish a template.
|
|
163
|
-
|
|
164
|
-
A storage or attention-refresh failure can reject after publication commits. The committed template retains the complete latest version so history and numbered-version previews remain readable if the history insert fails; a later declaration or publication repairs that row before replacing the snapshot. Retry the same declaration after resolving the storage problem. An indeterminate database mutation rejects without automatic retry or rollback: rejection is not proof that nothing changed.
|
|
165
|
+
A storage or attention-refresh failure can reject after publication commits. The committed template retains the complete latest version so history and numbered-version previews remain readable if the history insert fails; a later publication repairs that row before replacing the snapshot. An indeterminate database mutation rejects without automatic retry or rollback: rejection is not proof that nothing changed.
|
|
165
166
|
|
|
166
167
|
### DeclareTemplateCategory
|
|
167
168
|
|
|
@@ -169,13 +170,13 @@ A storage or attention-refresh failure can reject after publication commits. The
|
|
|
169
170
|
interface TemplateCategoryDeclaration {
|
|
170
171
|
tenantId: string;
|
|
171
172
|
id: string; // lowercase letters, digits and dashes
|
|
172
|
-
label:
|
|
173
|
+
label: LocalizedText; // { en: "…", fr: "…" }, en required
|
|
173
174
|
icon: string; // a Phosphor icon, such as "i-ph-repeat"
|
|
174
175
|
}
|
|
175
176
|
|
|
176
177
|
interface DeclareTemplateCategoryResult {
|
|
177
178
|
id: string;
|
|
178
|
-
outcome: "created" | "
|
|
179
|
+
outcome: "created" | "kept";
|
|
179
180
|
}
|
|
180
181
|
|
|
181
182
|
declare function DeclareTemplateCategory(
|
|
@@ -183,30 +184,42 @@ declare function DeclareTemplateCategory(
|
|
|
183
184
|
): Promise<DeclareTemplateCategoryResult>;
|
|
184
185
|
```
|
|
185
186
|
|
|
186
|
-
Adds a category to the workspace settings (`created`)
|
|
187
|
+
Adds a category to the workspace settings (`created`). An id the settings already hold, the defaults `orders`, `account`, `billing`, `marketing` and `forms` among them, is left as it is (`kept`). 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
188
|
|
|
188
|
-
###
|
|
189
|
+
### DeclareSender
|
|
190
|
+
|
|
191
|
+
```ts [Contract]
|
|
192
|
+
interface SenderDeclaration {
|
|
193
|
+
tenantId: string;
|
|
194
|
+
email: string; // the address e-mails are sent from
|
|
195
|
+
name?: string; // shown next to it
|
|
196
|
+
replyTo?: string; // replies go to the sender address when absent
|
|
197
|
+
}
|
|
189
198
|
|
|
190
|
-
|
|
199
|
+
declare function DeclareSender(declaration: SenderDeclaration): Promise<void>;
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
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.
|
|
203
|
+
|
|
204
|
+
### When to call
|
|
191
205
|
|
|
192
|
-
|
|
193
|
-
- in `start()`, perform explicitly scoped global work, not consumer registration that can race reconciliation. A `construct()` awaiting declarations would wait for database startup, which only runs after every `construct()` returned;
|
|
194
|
-
- in a `Hook.DATABASE_INITIALIZED` handler, do not await them either: the hook's handlers run one after the other.
|
|
206
|
+
Call these functions from a `Hook.TENANT_BEING_PROVISIONED` handler, registered in your module's `construct()`. The DMS fires that hook once for each tenant, when the tenant is created. For the `default` tenant, it fires on the DMS start that creates it, after every `DATABASE_INITIALIZED` handler has finished. A SaaS module fires it for each workspace it creates. The mailing tables are ready by then, so the calls do not wait for anything.
|
|
195
207
|
|
|
196
|
-
`start()`
|
|
208
|
+
Do not call them from `start()` or a `DATABASE_INITIALIZED` handler. They run on every boot, and the content a workspace starts with is written once. After that, it belongs to the workspace.
|
|
197
209
|
|
|
198
210
|
```ts docs-check
|
|
211
|
+
import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
|
|
199
212
|
import {
|
|
200
213
|
DeclareTemplate,
|
|
201
214
|
DeclareTemplateCategory,
|
|
202
215
|
} from "@antelopejs/interface-dms-mailing";
|
|
203
216
|
|
|
204
|
-
|
|
205
|
-
await DeclareTemplateCategory({ tenantId, id: "subscriptions", label: "Subscriptions", icon: "i-ph-repeat" });
|
|
206
|
-
|
|
217
|
+
async function declareMailingContent(tenantId: string): Promise<void> {
|
|
218
|
+
await DeclareTemplateCategory({ tenantId, id: "subscriptions", label: { en: "Subscriptions", fr: "Abonnements" }, icon: "i-ph-repeat" });
|
|
219
|
+
await DeclareTemplate({
|
|
207
220
|
tenantId,
|
|
208
221
|
slug: "subscription-renewed",
|
|
209
|
-
name: "Subscription renewed",
|
|
222
|
+
name: { en: "Subscription renewed", fr: "Abonnement renouvelé" },
|
|
210
223
|
category: "subscriptions",
|
|
211
224
|
content: {
|
|
212
225
|
locales: {
|
|
@@ -232,45 +245,15 @@ export async function declareMailingContent(tenantId: string): Promise<void> {
|
|
|
232
245
|
testData: { customer: { firstName: "Sofie" }, plan: { name: "Pro" } },
|
|
233
246
|
author: "Release script",
|
|
234
247
|
});
|
|
235
|
-
if (result.outcome === "kept") {
|
|
236
|
-
// Preserve the user's content and lifecycle; it may be archived.
|
|
237
|
-
}
|
|
238
248
|
}
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
### Initialize new SaaS workspaces
|
|
242
|
-
|
|
243
|
-
For an application using dms-saas, register a durable `created` consumer through `RegisterWorkspaceLifecycleConsumer` from `@antelopejs/interface-dms-saas/workspace-lifecycle`. Register it synchronously in the application's `construct()`, before startup reconciliation begins; the async consumer executes later. The `created` transition follows workspace preparation and payment; delivery is **at least once**. `TENANT_BEING_PROVISIONED` is a different, prepayment hook: an error aborts creation, with no automatic replay or compensation of consumer effects.
|
|
244
|
-
|
|
245
|
-
The following is an **integration skeleton**, not a standalone persistence implementation. The application must implement the durable operation ledger and resource binding described in the comments before returning a receipt. Mailing neither depends on dms-saas nor registers this consumer.
|
|
246
|
-
|
|
247
|
-
```typescript
|
|
248
|
-
import { RegisterWorkspaceLifecycleConsumer } from "@antelopejs/interface-dms-saas/workspace-lifecycle";
|
|
249
|
-
import { declareMailingContent } from "./mailing-content"; // application function above
|
|
250
249
|
|
|
251
250
|
export function construct(): void {
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
transitions: ["created"],
|
|
255
|
-
async consume({ tenantId, operationId }) {
|
|
256
|
-
// Application responsibility: deduplicate concurrent/replayed operationId
|
|
257
|
-
// durably, returning the recorded receipt for completed operations.
|
|
258
|
-
await declareMailingContent(tenantId);
|
|
259
|
-
// Persist the resource bindings and completed operation before returning
|
|
260
|
-
// its durable receiptId. A crash here must be recoverable on redelivery.
|
|
261
|
-
// Return { receiptId, ... } from that application-owned durable record.
|
|
262
|
-
throw new Error("Implement durable operation binding and receipt storage");
|
|
263
|
-
},
|
|
251
|
+
RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
|
|
252
|
+
await declareMailingContent(tenantId);
|
|
264
253
|
});
|
|
265
254
|
}
|
|
266
255
|
```
|
|
267
256
|
|
|
268
|
-
Use `operationId` as the durable deduplication key. Idempotent declarations make their own retries safe; they do not make arbitrary consumer side effects exactly-once. Never acknowledge success with a fabricated receipt or before resources are durably associated with the operation. Do not await declarations from `construct()` while database startup is still blocked; consumer registration and consumer execution are distinct.
|
|
269
|
-
|
|
270
|
-
### Update existing SaaS workspaces
|
|
271
|
-
|
|
272
|
-
A new deployment does not emit `created` for every existing tenant. Apply code updates or backfills through an application-owned, authorized tenant inventory. For each candidate, check `IsWorkspaceProvisioningCommitted(tenantId)` from the same workspace-lifecycle entry point before declaring or importing. Proceed only on `true`; skip an uncommitted tenant, and treat lookup/inventory errors as failures, never permission to proceed. Preserve progress for retries and coordinate category/settings writers. This is separate from initializing a newly created workspace, and it must never silently fall back to the default tenant.
|
|
273
|
-
|
|
274
257
|
## ImportSends
|
|
275
258
|
|
|
276
259
|
```ts [Contract]
|
|
@@ -313,7 +296,7 @@ declare function ImportSends(params: SendImport): Promise<ImportSendsResult>;
|
|
|
313
296
|
|
|
314
297
|
**An import, not a send.** `SendTemplate` stamps every send with the current time, and the Overview, the template statistics and the send log read sends by that date: history from another provider, or a demo data set, cannot be replayed through it. `ImportSends` writes past sends with their own `sentAt` and events instead. Nothing is delivered, and no suppression, realtime update, automation or owner notification follows: import the suppression list separately if the old provider kept one.
|
|
315
298
|
|
|
316
|
-
Each entry names a template of the workspace (its published version is recorded) and is keyed by its `importId`: an entry imported before is skipped untouched, so
|
|
299
|
+
Each entry names a template of the workspace (its published version is recorded) and is keyed by its `importId`: an entry imported before is skipped untouched, so a retried provisioning imports nothing twice. The events can come in any order; the send's status, open and click counters, error and soft-bounce flag follow from them as if the webhook had reported them, and an entry without events is `sent`. An unknown template rejects the whole call with `template_not_found` before anything is written; an invalid entry rejects it with `invalid_import`, naming the field (`sends.3.to`). The log retention applies to imported sends like to any other: one older than the workspace's retention (90 days by default) goes at the next nightly run, so a demo data set should stay within it.
|
|
317
300
|
|
|
318
301
|
Events are sorted by `at` and deduplicated before storage and counting: `details.eventId` identifies provider retries; without it, the type, timestamp and serialized details must match. The earliest sorted occurrence is kept. Import IDs are scoped by tenant, not by provider: prefix them when importing more than one provider's identifier space.
|
|
319
302
|
|
|
@@ -340,4 +323,6 @@ All blocks share `BlockBase`: `id: string`, the discriminant `type: BlockType`,
|
|
|
340
323
|
|
|
341
324
|
`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
325
|
|
|
326
|
+
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.
|
|
327
|
+
|
|
343
328
|
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.
|
|
3
|
+
"version": "0.9.1",
|
|
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",
|
|
@@ -57,6 +57,7 @@
|
|
|
57
57
|
"@antelopejs/interface-email": ">=0.0.6 <1.0.0"
|
|
58
58
|
},
|
|
59
59
|
"devDependencies": {
|
|
60
|
+
"@antelopejs/interface-dms": ">=0.9.0 <1.0.0",
|
|
60
61
|
"@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
|
|
61
62
|
"@types/node": "^24.0.0",
|
|
62
63
|
"oxfmt": "^0.66.0",
|