@antelopejs/interface-dms-mailing 0.10.0 → 0.10.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
@@ -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,7 +63,7 @@ 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
 
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 six backend functions and the template types below. `SendTemplate` sends, `RecordEmailEvent` reports provider events, `DeclareTemplate`, `DeclareTemplateCategory` and `DeclareSender` ship templates, categories and the sender 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.
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 six 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.
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.10.0",
3
+ "version": "0.10.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",
@@ -61,7 +61,7 @@
61
61
  "@antelopejs/interface-database": ">=0.3.0 <1.0.0",
62
62
  "@antelopejs/interface-database-decorators": ">=0.2.0 <1.0.0",
63
63
  "@antelopejs/interface-dms": ">=0.12.0 <1.0.0",
64
- "@antelopejs/tooling-configs": ">=0.2.18 <1.0.0",
64
+ "@antelopejs/tooling-configs": ">=0.3.3 <1.0.0",
65
65
  "@types/node": "^24.0.0",
66
66
  "release-it": "^19.2.4",
67
67
  "release-it-changelogen": "^0.1.0",