@terreno/comms 57.18.0 → 57.20.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/CHANGELOG.md +2074 -0
- package/dist/templates.d.ts +18 -3
- package/dist/templates.js +22 -12
- package/package.json +3 -3
- package/src/templates.test.ts +93 -0
- package/src/templates.ts +42 -14
package/dist/templates.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type SecurityMailTemplateId } from "@terreno/api";
|
|
1
2
|
export interface MessageTemplate {
|
|
2
3
|
html?: string;
|
|
3
4
|
subject: string;
|
|
@@ -7,13 +8,27 @@ export interface RenderTemplateOptions {
|
|
|
7
8
|
data: Record<string, unknown>;
|
|
8
9
|
template: MessageTemplate;
|
|
9
10
|
}
|
|
10
|
-
|
|
11
|
+
/**
|
|
12
|
+
* Auth mail templates: the reset/verify links, plus the security notifications
|
|
13
|
+
* `AccountSecurityApp` sends (`securityPasswordChanged`, `securityPasskeyAdded`, ...).
|
|
14
|
+
*/
|
|
15
|
+
export type AuthMailTemplateId = "resetPassword" | "verifyEmail" | SecurityMailTemplateId;
|
|
11
16
|
export interface RenderAuthMailOptions {
|
|
17
|
+
/**
|
|
18
|
+
* Extra placeholder values. Security notifications pass `actor`, `orgClause`, `orgReference`,
|
|
19
|
+
* `providerName`, `occurredAt`, `appUrl`, and `secureAccountLine`.
|
|
20
|
+
*/
|
|
21
|
+
data?: Record<string, string>;
|
|
12
22
|
publicAppUrl: string;
|
|
13
23
|
templateId: AuthMailTemplateId;
|
|
14
|
-
token
|
|
24
|
+
/** The reset/verify token. Security notifications carry none. */
|
|
25
|
+
token?: string;
|
|
15
26
|
templates?: Partial<Record<AuthMailTemplateId, MessageTemplate>>;
|
|
16
27
|
}
|
|
17
28
|
export declare const DEFAULT_AUTH_MAIL_TEMPLATES: Record<AuthMailTemplateId, MessageTemplate>;
|
|
18
29
|
export declare const renderTemplate: ({ data, template }: RenderTemplateOptions) => MessageTemplate;
|
|
19
|
-
|
|
30
|
+
/**
|
|
31
|
+
* Renders an auth mail template. HTML bodies get HTML-escaped values, so data such as an org
|
|
32
|
+
* name cannot inject markup; subject and text get the raw values.
|
|
33
|
+
*/
|
|
34
|
+
export declare const renderAuthMail: ({ data, publicAppUrl, templateId, token, templates, }: RenderAuthMailOptions) => MessageTemplate;
|
package/dist/templates.js
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.renderAuthMail = exports.renderTemplate = exports.DEFAULT_AUTH_MAIL_TEMPLATES = void 0;
|
|
4
|
+
const api_1 = require("@terreno/api");
|
|
4
5
|
exports.DEFAULT_AUTH_MAIL_TEMPLATES = {
|
|
6
|
+
...api_1.DEFAULT_SECURITY_MAIL_TEMPLATES,
|
|
5
7
|
resetPassword: {
|
|
6
8
|
html: '<p><a href="{{resetUrl}}">Reset your password</a></p>',
|
|
7
9
|
subject: "Reset your password",
|
|
@@ -34,18 +36,26 @@ const authMailUrl = (publicAppUrl, path, token) => {
|
|
|
34
36
|
const base = publicAppUrl.replace(/\/$/, "");
|
|
35
37
|
return `${base}${path}?token=${encodeURIComponent(token)}`;
|
|
36
38
|
};
|
|
37
|
-
|
|
39
|
+
/**
|
|
40
|
+
* Renders an auth mail template. HTML bodies get HTML-escaped values, so data such as an org
|
|
41
|
+
* name cannot inject markup; subject and text get the raw values.
|
|
42
|
+
*/
|
|
43
|
+
const renderAuthMail = ({ data = {}, publicAppUrl, templateId, token = "", templates, }) => {
|
|
38
44
|
const template = templates?.[templateId] ?? exports.DEFAULT_AUTH_MAIL_TEMPLATES[templateId];
|
|
39
|
-
const
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
45
|
+
const values = {
|
|
46
|
+
...data,
|
|
47
|
+
publicAppUrl: publicAppUrl.replace(/\/$/, ""),
|
|
48
|
+
resetUrl: authMailUrl(publicAppUrl, "/resetPassword", token),
|
|
49
|
+
token,
|
|
50
|
+
verifyUrl: authMailUrl(publicAppUrl, "/verifyEmail", token),
|
|
51
|
+
};
|
|
52
|
+
const htmlValues = Object.fromEntries(Object.entries(values).map(([key, value]) => [key, (0, api_1.escapeMailHtml)(value)]));
|
|
53
|
+
const { html, ...plain } = template;
|
|
54
|
+
return {
|
|
55
|
+
...(html === undefined
|
|
56
|
+
? {}
|
|
57
|
+
: { html: (0, exports.renderTemplate)({ data: htmlValues, template: { html, subject: "" } }).html }),
|
|
58
|
+
...(0, exports.renderTemplate)({ data: values, template: plain }),
|
|
59
|
+
};
|
|
50
60
|
};
|
|
51
61
|
exports.renderAuthMail = renderAuthMail;
|
package/package.json
CHANGED
|
@@ -4,14 +4,14 @@
|
|
|
4
4
|
"url": "https://github.com/TerrenoLabs/terreno/issues"
|
|
5
5
|
},
|
|
6
6
|
"dependencies": {
|
|
7
|
-
"@terreno/api": "57.
|
|
7
|
+
"@terreno/api": "57.20.0",
|
|
8
8
|
"libphonenumber-js": "^1.13.8",
|
|
9
9
|
"luxon": "^3.7.2"
|
|
10
10
|
},
|
|
11
11
|
"description": "Pluggable mail, SMS, push, and verification providers — part of Terreno, the batteries-included TypeScript framework for universal apps.",
|
|
12
12
|
"devDependencies": {
|
|
13
13
|
"@biomejs/biome": "^2.3.6",
|
|
14
|
-
"@terreno/test": "57.
|
|
14
|
+
"@terreno/test": "57.20.0",
|
|
15
15
|
"@types/bun": "^1.4.0",
|
|
16
16
|
"@types/express": "^5.0.6",
|
|
17
17
|
"@types/luxon": "^3.7.1",
|
|
@@ -89,5 +89,5 @@
|
|
|
89
89
|
"test:coverage": "bun run ../scripts/check-coverage.ts"
|
|
90
90
|
},
|
|
91
91
|
"types": "dist/index.d.ts",
|
|
92
|
-
"version": "57.
|
|
92
|
+
"version": "57.20.0"
|
|
93
93
|
}
|
package/src/templates.test.ts
CHANGED
|
@@ -1,4 +1,10 @@
|
|
|
1
1
|
import {describe, it} from "bun:test";
|
|
2
|
+
import {
|
|
3
|
+
DEFAULT_SECURITY_MAIL_TEMPLATES,
|
|
4
|
+
renderSecurityMail,
|
|
5
|
+
SECURITY_MAIL_TEMPLATE_IDS,
|
|
6
|
+
type SecurityMailRenderer,
|
|
7
|
+
} from "@terreno/api";
|
|
2
8
|
import {assert} from "chai";
|
|
3
9
|
|
|
4
10
|
import {renderAuthMail, renderTemplate} from "./templates";
|
|
@@ -97,3 +103,90 @@ describe("auth mail templates", () => {
|
|
|
97
103
|
});
|
|
98
104
|
});
|
|
99
105
|
});
|
|
106
|
+
|
|
107
|
+
describe("security notification templates", () => {
|
|
108
|
+
const data = {
|
|
109
|
+
actor: "An administrator",
|
|
110
|
+
appUrl: "https://app.example.com",
|
|
111
|
+
occurredAt: "October 23, 2026 at 14:05 UTC",
|
|
112
|
+
orgClause: " at Acme <Clinic>",
|
|
113
|
+
orgReference: "Acme <Clinic>",
|
|
114
|
+
providerName: "Google",
|
|
115
|
+
secureAccountLine: "If you did not expect this change, contact support right away.",
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
for (const templateId of SECURITY_MAIL_TEMPLATE_IDS) {
|
|
119
|
+
it(`renders ${templateId} with subject, text, and html`, (): void => {
|
|
120
|
+
const rendered = renderAuthMail({data, publicAppUrl: "https://app.example.com", templateId});
|
|
121
|
+
|
|
122
|
+
assert.equal(rendered.subject, DEFAULT_SECURITY_MAIL_TEMPLATES[templateId].subject);
|
|
123
|
+
assert.include(rendered.text, "October 23, 2026 at 14:05 UTC");
|
|
124
|
+
assert.include(rendered.text, "contact support right away");
|
|
125
|
+
assert.notInclude(rendered.text, "{{");
|
|
126
|
+
assert.notInclude(rendered.text, "token=");
|
|
127
|
+
assert.include(rendered.html, "<p>");
|
|
128
|
+
assert.notInclude(rendered.html, "{{");
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
it("fits AccountSecurityApp notifications.render", (): void => {
|
|
133
|
+
const render: SecurityMailRenderer = renderAuthMail;
|
|
134
|
+
const rendered = render({
|
|
135
|
+
data,
|
|
136
|
+
publicAppUrl: "https://app.example.com",
|
|
137
|
+
templateId: "securitySignInLinkIssued",
|
|
138
|
+
});
|
|
139
|
+
assert.equal(rendered.subject, "A sign-in link was created for your account");
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
it("matches the @terreno/api fallback renderer for the same input", (): void => {
|
|
143
|
+
for (const templateId of SECURITY_MAIL_TEMPLATE_IDS) {
|
|
144
|
+
assert.deepEqual(
|
|
145
|
+
renderAuthMail({data, publicAppUrl: "https://app.example.com", templateId}),
|
|
146
|
+
renderSecurityMail({data, templateId})
|
|
147
|
+
);
|
|
148
|
+
}
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
it("escapes data in the html body only", (): void => {
|
|
152
|
+
const rendered = renderAuthMail({
|
|
153
|
+
data,
|
|
154
|
+
publicAppUrl: "https://app.example.com",
|
|
155
|
+
templateId: "securityPasskeyRemoved",
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
assert.include(rendered.text, "An administrator at Acme <Clinic> removed a passkey");
|
|
159
|
+
assert.include(rendered.html, "An administrator at Acme <Clinic> removed a passkey");
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
it("applies app overrides for security template ids", (): void => {
|
|
163
|
+
const rendered = renderAuthMail({
|
|
164
|
+
data,
|
|
165
|
+
publicAppUrl: "https://app.example.com",
|
|
166
|
+
templateId: "securityTwoFactorDisabled",
|
|
167
|
+
templates: {securityTwoFactorDisabled: {subject: "2FA off ({{actor}})", text: "{{appUrl}}"}},
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
assert.deepEqual(rendered, {
|
|
171
|
+
subject: "2FA off (An administrator)",
|
|
172
|
+
text: "https://app.example.com",
|
|
173
|
+
});
|
|
174
|
+
});
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
describe("html escaping in auth mail", () => {
|
|
178
|
+
it("escapes & in the html href and keeps it raw in the text", (): void => {
|
|
179
|
+
const rendered = renderAuthMail({
|
|
180
|
+
publicAppUrl: "https://app.example.com/?tenant=a&lang=en",
|
|
181
|
+
templateId: "resetPassword",
|
|
182
|
+
token: "abc123",
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
assert.include(
|
|
186
|
+
rendered.html,
|
|
187
|
+
'href="https://app.example.com/?tenant=a&lang=en/resetPassword'
|
|
188
|
+
);
|
|
189
|
+
assert.notInclude(rendered.html, "tenant=a&lang");
|
|
190
|
+
assert.include(rendered.text, "https://app.example.com/?tenant=a&lang=en/resetPassword");
|
|
191
|
+
});
|
|
192
|
+
});
|
package/src/templates.ts
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
import {
|
|
2
|
+
DEFAULT_SECURITY_MAIL_TEMPLATES,
|
|
3
|
+
escapeMailHtml,
|
|
4
|
+
type SecurityMailTemplateId,
|
|
5
|
+
} from "@terreno/api";
|
|
6
|
+
|
|
1
7
|
export interface MessageTemplate {
|
|
2
8
|
html?: string;
|
|
3
9
|
subject: string;
|
|
@@ -9,16 +15,27 @@ export interface RenderTemplateOptions {
|
|
|
9
15
|
template: MessageTemplate;
|
|
10
16
|
}
|
|
11
17
|
|
|
12
|
-
|
|
18
|
+
/**
|
|
19
|
+
* Auth mail templates: the reset/verify links, plus the security notifications
|
|
20
|
+
* `AccountSecurityApp` sends (`securityPasswordChanged`, `securityPasskeyAdded`, ...).
|
|
21
|
+
*/
|
|
22
|
+
export type AuthMailTemplateId = "resetPassword" | "verifyEmail" | SecurityMailTemplateId;
|
|
13
23
|
|
|
14
24
|
export interface RenderAuthMailOptions {
|
|
25
|
+
/**
|
|
26
|
+
* Extra placeholder values. Security notifications pass `actor`, `orgClause`, `orgReference`,
|
|
27
|
+
* `providerName`, `occurredAt`, `appUrl`, and `secureAccountLine`.
|
|
28
|
+
*/
|
|
29
|
+
data?: Record<string, string>;
|
|
15
30
|
publicAppUrl: string;
|
|
16
31
|
templateId: AuthMailTemplateId;
|
|
17
|
-
token
|
|
32
|
+
/** The reset/verify token. Security notifications carry none. */
|
|
33
|
+
token?: string;
|
|
18
34
|
templates?: Partial<Record<AuthMailTemplateId, MessageTemplate>>;
|
|
19
35
|
}
|
|
20
36
|
|
|
21
37
|
export const DEFAULT_AUTH_MAIL_TEMPLATES: Record<AuthMailTemplateId, MessageTemplate> = {
|
|
38
|
+
...DEFAULT_SECURITY_MAIL_TEMPLATES,
|
|
22
39
|
resetPassword: {
|
|
23
40
|
html: '<p><a href="{{resetUrl}}">Reset your password</a></p>',
|
|
24
41
|
subject: "Reset your password",
|
|
@@ -57,22 +74,33 @@ const authMailUrl = (publicAppUrl: string, path: string, token: string): string
|
|
|
57
74
|
return `${base}${path}?token=${encodeURIComponent(token)}`;
|
|
58
75
|
};
|
|
59
76
|
|
|
77
|
+
/**
|
|
78
|
+
* Renders an auth mail template. HTML bodies get HTML-escaped values, so data such as an org
|
|
79
|
+
* name cannot inject markup; subject and text get the raw values.
|
|
80
|
+
*/
|
|
60
81
|
export const renderAuthMail = ({
|
|
82
|
+
data = {},
|
|
61
83
|
publicAppUrl,
|
|
62
84
|
templateId,
|
|
63
|
-
token,
|
|
85
|
+
token = "",
|
|
64
86
|
templates,
|
|
65
87
|
}: RenderAuthMailOptions): MessageTemplate => {
|
|
66
88
|
const template = templates?.[templateId] ?? DEFAULT_AUTH_MAIL_TEMPLATES[templateId];
|
|
67
|
-
const
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
}
|
|
89
|
+
const values: Record<string, string> = {
|
|
90
|
+
...data,
|
|
91
|
+
publicAppUrl: publicAppUrl.replace(/\/$/, ""),
|
|
92
|
+
resetUrl: authMailUrl(publicAppUrl, "/resetPassword", token),
|
|
93
|
+
token,
|
|
94
|
+
verifyUrl: authMailUrl(publicAppUrl, "/verifyEmail", token),
|
|
95
|
+
};
|
|
96
|
+
const htmlValues = Object.fromEntries(
|
|
97
|
+
Object.entries(values).map(([key, value]) => [key, escapeMailHtml(value)])
|
|
98
|
+
);
|
|
99
|
+
const {html, ...plain} = template;
|
|
100
|
+
return {
|
|
101
|
+
...(html === undefined
|
|
102
|
+
? {}
|
|
103
|
+
: {html: renderTemplate({data: htmlValues, template: {html, subject: ""}}).html}),
|
|
104
|
+
...renderTemplate({data: values, template: plain}),
|
|
105
|
+
};
|
|
78
106
|
};
|