@antelopejs/interface-dms-mailing 0.10.0 → 0.11.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 +4 -3
- package/dist/index.d.ts +10 -0
- package/dist/index.js +2 -1
- package/docs/1.index.md +23 -3
- package/package.json +11 -11
package/README.md
CHANGED
|
@@ -17,6 +17,7 @@ The AntelopeJS interface to send DMS mailing templates and report e-mail events
|
|
|
17
17
|
- Reports a provider event (delivered, opened, clicked, bounced…) against the send it belongs to (`RecordEmailEvent`).
|
|
18
18
|
- Ships templates and template categories as code when a workspace is provisioned (`DeclareTemplate`, `DeclareTemplateCategory`). A declaration writes once: a template is created already published, and a slug or category id the workspace already has is left as it is.
|
|
19
19
|
- Writes the workspace sender when a workspace is provisioned (`DeclareSender`).
|
|
20
|
+
- Sets the workspace webhook secret from code, keeping one the workspace owner set or rotated (`DeclareWebhookSecret`).
|
|
20
21
|
- Imports past sends and their events with their own dates, for a demo data set or a move from another provider (`ImportSends`).
|
|
21
22
|
- Exports the template and send types (`Block`, `TemplateContent`, `VariableDefinition`, `SendStatus`, `EmailEvent`…) for code that builds or inspects templates.
|
|
22
23
|
- Keeps your module independent of the implementation, [`@antelopejs/dms-mailing`](https://www.npmjs.com/package/@antelopejs/dms-mailing).
|
|
@@ -62,14 +63,14 @@ A recipient on the workspace's suppression list gets no e-mail, and its result h
|
|
|
62
63
|
|
|
63
64
|
## Compatibility
|
|
64
65
|
|
|
65
|
-
A `@antelopejs/dms-mailing` release implements one minor line of this interface. The `@antelopejs/interface-dms-mailing` row of the compatibility block in the [module README](../dms-mailing/README.md#compatibility) gives that range. Use a module release whose range covers the interface release your code imports. `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `ImportSends` each take an explicit `tenantId`. The interface declares these dependencies:
|
|
66
|
+
A `@antelopejs/dms-mailing` release implements one minor line of this interface. The `@antelopejs/interface-dms-mailing` row of the compatibility block in the [module README](../dms-mailing/README.md#compatibility) gives that range. Use a module release whose range covers the interface release your code imports. `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret` and `ImportSends` each take an explicit `tenantId`. The interface declares these dependencies:
|
|
66
67
|
|
|
67
68
|
<!-- antelopejs-docs-compat:start -->
|
|
68
69
|
|
|
69
70
|
| Package | Supported | Tested with |
|
|
70
71
|
| ----------------------------- | ---------------- | ----------- |
|
|
71
|
-
| `@antelopejs/interface-core` | `>=0.
|
|
72
|
-
| `@antelopejs/interface-email` | `>=0.0
|
|
72
|
+
| `@antelopejs/interface-core` | `>=0.5.0 <0.6.0` | `0.5.1` |
|
|
73
|
+
| `@antelopejs/interface-email` | `>=0.2.0 <0.3.0` | `0.2.1` |
|
|
73
74
|
|
|
74
75
|
<!-- antelopejs-docs-compat:end -->
|
|
75
76
|
|
package/dist/index.d.ts
CHANGED
|
@@ -153,6 +153,15 @@ export interface SenderDeclaration {
|
|
|
153
153
|
name?: string;
|
|
154
154
|
replyTo?: string;
|
|
155
155
|
}
|
|
156
|
+
export interface WebhookSecretDeclaration {
|
|
157
|
+
tenantId: string;
|
|
158
|
+
secret: string;
|
|
159
|
+
replaceRotated?: boolean;
|
|
160
|
+
}
|
|
161
|
+
export type WebhookSecretOutcome = "set" | "unchanged" | "kept";
|
|
162
|
+
export interface DeclareWebhookSecretResult {
|
|
163
|
+
outcome: WebhookSecretOutcome;
|
|
164
|
+
}
|
|
156
165
|
export interface ImportedSendEvent {
|
|
157
166
|
type: SendEventType;
|
|
158
167
|
at: Date;
|
|
@@ -183,4 +192,5 @@ export interface ImportSendsResult {
|
|
|
183
192
|
export declare const DeclareTemplate: (declaration: TemplateDeclaration) => Promise<DeclareTemplateResult>;
|
|
184
193
|
export declare const DeclareTemplateCategory: (declaration: TemplateCategoryDeclaration) => Promise<DeclareTemplateCategoryResult>;
|
|
185
194
|
export declare const DeclareSender: (declaration: SenderDeclaration) => Promise<void>;
|
|
195
|
+
export declare const DeclareWebhookSecret: (declaration: WebhookSecretDeclaration) => Promise<DeclareWebhookSecretResult>;
|
|
186
196
|
export declare const ImportSends: (params: SendImport) => Promise<ImportSendsResult>;
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.ImportSends = exports.DeclareSender = exports.DeclareTemplateCategory = exports.DeclareTemplate = exports.LOCALIZED_TEXT_FALLBACK_LOCALE = exports.RecordEmailEvent = exports.SendTemplate = void 0;
|
|
3
|
+
exports.ImportSends = exports.DeclareWebhookSecret = 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)();
|
|
@@ -8,4 +8,5 @@ exports.LOCALIZED_TEXT_FALLBACK_LOCALE = "en";
|
|
|
8
8
|
exports.DeclareTemplate = (0, interface_core_1.InterfaceFunction)();
|
|
9
9
|
exports.DeclareTemplateCategory = (0, interface_core_1.InterfaceFunction)();
|
|
10
10
|
exports.DeclareSender = (0, interface_core_1.InterfaceFunction)();
|
|
11
|
+
exports.DeclareWebhookSecret = (0, interface_core_1.InterfaceFunction)();
|
|
11
12
|
exports.ImportSends = (0, interface_core_1.InterfaceFunction)();
|
package/docs/1.index.md
CHANGED
|
@@ -4,9 +4,9 @@ description: Consumer contract for sending templates and recording provider even
|
|
|
4
4
|
mode: reference
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
`@antelopejs/interface-dms-mailing` exports
|
|
7
|
+
`@antelopejs/interface-dms-mailing` exports seven backend functions and the template types below. `SendTemplate` sends, `RecordEmailEvent` reports provider events, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `DeclareWebhookSecret` ship templates, categories, the sender and the webhook secret as code, and `ImportSends` imports past sends. They need `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider loaded, and are imported from the interface package, not the runtime module's services.
|
|
8
8
|
|
|
9
|
-
All
|
|
9
|
+
All seven take an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints, so the calling module authenticates and authorizes the tenant. A missing implementation or a storage failure rejects the promise.
|
|
10
10
|
|
|
11
11
|
## Per-recipient results
|
|
12
12
|
|
|
@@ -119,7 +119,7 @@ An accepted event updates the send's timeline, status and counters, publishes re
|
|
|
119
119
|
|
|
120
120
|
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)). From then on it belongs to the tenant, and 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.
|
|
121
121
|
|
|
122
|
-
`DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `ImportSends` require an explicit `tenantId`, in TypeScript and at runtime. A missing, empty or blank one rejects before any write with `invalid_template`, `invalid_category`, `invalid_sender` or `invalid_import` respectively, naming `tenantId`. No default applies, and an explicit `DEFAULT_TENANT_ID` is valid. It names the target but proves neither authorization nor provisioning, which the calling code enforces. `SendTemplate` and `RecordEmailEvent` do not run this check.
|
|
122
|
+
`DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret` and `ImportSends` require an explicit `tenantId`, in TypeScript and at runtime. A missing, empty or blank one rejects before any write with `invalid_template`, `invalid_category`, `invalid_sender`, `invalid_webhook_secret` or `invalid_import` respectively, naming `tenantId`. No default applies, and an explicit `DEFAULT_TENANT_ID` is valid. It names the target but proves neither authorization nor provisioning, which the calling code enforces. `SendTemplate` and `RecordEmailEvent` do not run this check.
|
|
123
123
|
|
|
124
124
|
### Names and labels in several languages
|
|
125
125
|
|
|
@@ -205,6 +205,26 @@ declare function DeclareSender(declaration: SenderDeclaration): Promise<void>;
|
|
|
205
205
|
|
|
206
206
|
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. It belongs in `Hook.TENANT_BEING_PROVISIONED`, not on every boot, because the settings are the user's afterwards and a later call overwrites their changes. The address and reply-to follow the settings form's rules (an internationalized domain is stored in ASCII form), and a missing or invalid address rejects with `invalid_sender`, naming the field. Like `DeclareTemplateCategory`, it rewrites the whole settings row, so the two are awaited one after the other for a workspace.
|
|
207
207
|
|
|
208
|
+
### `DeclareWebhookSecret`
|
|
209
|
+
|
|
210
|
+
```ts [Contract]
|
|
211
|
+
interface WebhookSecretDeclaration {
|
|
212
|
+
tenantId: string;
|
|
213
|
+
secret: string; // 32 to 120 characters
|
|
214
|
+
replaceRotated?: boolean; // replace a secret the workspace owner set or rotated
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
type WebhookSecretOutcome = "set" | "unchanged" | "kept";
|
|
218
|
+
|
|
219
|
+
declare function DeclareWebhookSecret(
|
|
220
|
+
declaration: WebhookSecretDeclaration,
|
|
221
|
+
): Promise<{ outcome: WebhookSecretOutcome }>;
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Sets the secret a provider sends with each webhook event, for a project that needs a known one, such as a demo whose screenshots show the settings page or a provider configured ahead of the workspace. A new workspace starts with a random secret, which a declaration replaces (`set`). Declaring the stored secret again changes nothing (`unchanged`), so the call is safe on every start. A secret the workspace owner typed in the settings or rotated there is theirs: a declaration leaves it in place (`kept`) unless it passes `replaceRotated: true`. A secret stored by a module release without `DeclareWebhookSecret` counts as the owner's.
|
|
225
|
+
|
|
226
|
+
The secret is never returned, and a refused one rejects with `invalid_webhook_secret`, naming the rule (`secret` too short or too long), never the value. The call writes the secret alone, so it does not overwrite settings another writer changes at the same time.
|
|
227
|
+
|
|
208
228
|
### When to call
|
|
209
229
|
|
|
210
230
|
The declarations belong in a `Hook.TENANT_BEING_PROVISIONED` handler that the module registers in `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 the tenant, 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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-dms-mailing",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.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",
|
|
@@ -47,21 +47,21 @@
|
|
|
47
47
|
"scripts": {
|
|
48
48
|
"build": "rimraf dist && tsc",
|
|
49
49
|
"prepack": "pnpm run build",
|
|
50
|
-
"release": "pnpm run build && pnpm --dir ../.. run lint && pnpm --dir ../.. run format:check && release-it",
|
|
50
|
+
"release": "pnpm run typecheck && pnpm run build && pnpm --dir ../.. run lint && pnpm --dir ../.. run format:check && release-it",
|
|
51
51
|
"typecheck": "tsc --noEmit"
|
|
52
52
|
},
|
|
53
53
|
"dependencies": {
|
|
54
|
-
"@antelopejs/interface-core": ">=0.
|
|
55
|
-
"@antelopejs/interface-email": ">=0.0
|
|
54
|
+
"@antelopejs/interface-core": ">=0.5.0 <0.6.0",
|
|
55
|
+
"@antelopejs/interface-email": ">=0.2.0 <0.3.0"
|
|
56
56
|
},
|
|
57
57
|
"devDependencies": {
|
|
58
|
-
"@antelopejs/interface-api": ">=0.3.
|
|
59
|
-
"@antelopejs/interface-api-util": ">=0.3.
|
|
60
|
-
"@antelopejs/interface-data-api": ">=0.
|
|
61
|
-
"@antelopejs/interface-database": ">=0.
|
|
62
|
-
"@antelopejs/interface-database-decorators": ">=0.
|
|
63
|
-
"@antelopejs/interface-dms": ">=0.
|
|
64
|
-
"@antelopejs/tooling-configs": ">=0.
|
|
58
|
+
"@antelopejs/interface-api": ">=0.3.3 <0.4.0",
|
|
59
|
+
"@antelopejs/interface-api-util": ">=0.3.2 <0.4.0",
|
|
60
|
+
"@antelopejs/interface-data-api": ">=0.8.0 <0.9.0",
|
|
61
|
+
"@antelopejs/interface-database": ">=0.4.0 <0.5.0",
|
|
62
|
+
"@antelopejs/interface-database-decorators": ">=0.5.0 <0.6.0",
|
|
63
|
+
"@antelopejs/interface-dms": ">=0.14.0 <0.15.0",
|
|
64
|
+
"@antelopejs/tooling-configs": ">=0.7.1 <0.8.0",
|
|
65
65
|
"@types/node": "^24.0.0",
|
|
66
66
|
"release-it": "^19.2.4",
|
|
67
67
|
"release-it-changelogen": "^0.1.0",
|