@pithy-sh/email 0.6.0 → 0.8.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 +8 -0
- package/dist/capability.d.ts +2 -2
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +23 -2
- package/dist/consent/consent.d.ts +57 -0
- package/dist/consent/consent.d.ts.map +1 -0
- package/dist/consent/consent.js +135 -0
- package/dist/data/emailEvent.d.ts +1 -1
- package/dist/data/emailEvent.d.ts.map +1 -1
- package/dist/data/emailEvent.js +2 -1
- package/dist/data/emailJob.d.ts +6 -2
- package/dist/data/emailJob.d.ts.map +1 -1
- package/dist/data/emailJob.js +8 -3
- package/dist/data/emailSuppression.d.ts +1 -1
- package/dist/data/emailSuppression.d.ts.map +1 -1
- package/dist/data/emailSuppression.js +2 -1
- package/dist/data/tables.d.ts +4 -4
- package/dist/http/guards.d.ts +2 -2
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +12 -0
- package/dist/processing/activities.d.ts +9 -0
- package/dist/processing/activities.d.ts.map +1 -0
- package/dist/processing/activities.js +40 -0
- package/dist/purge/contribution.d.ts +27 -0
- package/dist/purge/contribution.d.ts.map +1 -0
- package/dist/purge/contribution.js +67 -0
- package/dist/send/enqueue.d.ts +26 -7
- package/dist/send/enqueue.d.ts.map +1 -1
- package/dist/send/enqueue.js +36 -13
- package/dist/templates/messages.d.ts +1 -2
- package/dist/templates/messages.d.ts.map +1 -1
- package/dist/templates/messages.es.d.ts.map +1 -1
- package/dist/templates/messages.es.js +28 -0
- package/dist/templates/messages.js +35 -10
- package/dist/templates/precompiled.generated.d.ts +124 -0
- package/dist/templates/precompiled.generated.d.ts.map +1 -1
- package/dist/templates/precompiled.generated.js +1618 -0
- package/dist/templates/registry.d.ts.map +1 -1
- package/dist/templates/registry.js +106 -0
- package/dist/templates/samples.d.ts.map +1 -1
- package/dist/templates/samples.js +28 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
- package/src/capability.ts +33 -7
- package/src/consent/consent.ts +183 -0
- package/src/data/emailEvent.ts +2 -1
- package/src/data/emailJob.ts +21 -8
- package/src/data/emailSuppression.ts +2 -1
- package/src/http/guards.ts +14 -2
- package/src/processing/activities.ts +41 -0
- package/src/purge/contribution.ts +83 -0
- package/src/send/enqueue.ts +62 -24
- package/src/templates/messages.es.ts +41 -0
- package/src/templates/messages.ts +52 -11
- package/src/templates/precompiled.generated.ts +551 -0
- package/src/templates/registry.ts +159 -0
- package/src/templates/samples.ts +11 -0
- package/src/version.generated.ts +1 -1
package/src/http/guards.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
-
import type {
|
|
4
|
+
import type { AdminRouteDeclaration } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
|
|
5
5
|
import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
|
|
6
6
|
|
|
7
7
|
/**
|
|
@@ -112,42 +112,54 @@ export const EMAIL_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
|
|
|
112
112
|
* The summaries say what the operation is *for*. A client renders these next to a button somebody is
|
|
113
113
|
* about to press on a real person's mail.
|
|
114
114
|
*/
|
|
115
|
-
export function emailAdminRoutes(basePath: string):
|
|
115
|
+
export function emailAdminRoutes(basePath: string): AdminRouteDeclaration[] {
|
|
116
116
|
return [
|
|
117
117
|
{
|
|
118
118
|
method: "GET",
|
|
119
|
+
operation: "jobs.list",
|
|
119
120
|
path: `${basePath}/jobs`,
|
|
120
121
|
scope: EMAIL_JOBS_READ_SCOPE,
|
|
122
|
+
kind: "reads",
|
|
121
123
|
summary: "The send log, newest first, filtered by status. Recipients are masked in the list.",
|
|
122
124
|
},
|
|
123
125
|
{
|
|
124
126
|
method: "GET",
|
|
127
|
+
operation: "jobs.read",
|
|
125
128
|
path: `${basePath}/jobs/:id`,
|
|
126
129
|
scope: EMAIL_JOBS_READ_SCOPE,
|
|
130
|
+
kind: "reads",
|
|
127
131
|
summary: "One job in full — the recipient, the subject, and why it failed. Never the template variables.",
|
|
128
132
|
},
|
|
129
133
|
{
|
|
130
134
|
method: "POST",
|
|
135
|
+
operation: "jobs.retry",
|
|
131
136
|
path: `${basePath}/jobs/:id/retry`,
|
|
132
137
|
scope: EMAIL_JOBS_RETRY_SCOPE,
|
|
138
|
+
kind: "sends",
|
|
133
139
|
summary: "Queue a failed job again with a fresh attempt budget. Sends real mail.",
|
|
134
140
|
},
|
|
135
141
|
{
|
|
136
142
|
method: "GET",
|
|
143
|
+
operation: "suppressions.list",
|
|
137
144
|
path: `${basePath}/suppressions`,
|
|
138
145
|
scope: EMAIL_SUPPRESSIONS_READ_SCOPE,
|
|
146
|
+
kind: "reads",
|
|
139
147
|
summary: "Addresses this project will not send to, and why. Global — every environment shares it.",
|
|
140
148
|
},
|
|
141
149
|
{
|
|
142
150
|
method: "POST",
|
|
151
|
+
operation: "suppressions.add",
|
|
143
152
|
path: `${basePath}/suppressions`,
|
|
144
153
|
scope: EMAIL_SUPPRESSIONS_WRITE_SCOPE,
|
|
154
|
+
kind: "writes",
|
|
145
155
|
summary: "Block an address by hand, permanently or until a date. Recorded as a manual block.",
|
|
146
156
|
},
|
|
147
157
|
{
|
|
148
158
|
method: "POST",
|
|
159
|
+
operation: "suppressions.remove",
|
|
149
160
|
path: `${basePath}/suppressions/remove`,
|
|
150
161
|
scope: EMAIL_SUPPRESSIONS_DELETE_SCOPE,
|
|
162
|
+
kind: "deletes",
|
|
151
163
|
summary: "Unblock an address. Re-opens sending to somebody who bounced, complained, or opted out.",
|
|
152
164
|
},
|
|
153
165
|
];
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import type { ProcessingActivityInput, ProcessingRecipientInput } from "@pithy-sh/core/src/processing/activity";
|
|
5
|
+
import { EMAIL_MARKETING_PURPOSE, EMAIL_TRACKING_PURPOSE } from "../consent/consent";
|
|
6
|
+
|
|
7
|
+
/** The mail provider every send goes through. */
|
|
8
|
+
const EMAIL_SERVICE: ProcessingRecipientInput = {
|
|
9
|
+
name: "Cloudflare Email Service",
|
|
10
|
+
receives: "Each recipient's address and the message sent to it.",
|
|
11
|
+
classes: ["pii"],
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* What email does with personal data: it sends the mail the Worker enqueues, and, under each purpose's consent,
|
|
16
|
+
* marketing mail and open and click tracking.
|
|
17
|
+
*/
|
|
18
|
+
export const EMAIL_PROCESSING: readonly ProcessingActivityInput[] = [
|
|
19
|
+
{
|
|
20
|
+
id: "email.delivery",
|
|
21
|
+
purpose: "Send the mail a person's account needs — sign-in links, codes, notices — and keep its history.",
|
|
22
|
+
classes: ["pii"],
|
|
23
|
+
legalBasis: "contract",
|
|
24
|
+
recipients: [EMAIL_SERVICE],
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
id: "email.marketing",
|
|
28
|
+
purpose: "Send news and offers by email to a person who agreed to receive them.",
|
|
29
|
+
classes: ["pii"],
|
|
30
|
+
legalBasis: "consent",
|
|
31
|
+
consentPurpose: EMAIL_MARKETING_PURPOSE,
|
|
32
|
+
recipients: [EMAIL_SERVICE],
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
id: "email.tracking",
|
|
36
|
+
purpose: "Record when a person opens a message or follows a link in it, for a person who agreed to it.",
|
|
37
|
+
classes: ["pii"],
|
|
38
|
+
legalBasis: "consent",
|
|
39
|
+
consentPurpose: EMAIL_TRACKING_PURPOSE,
|
|
40
|
+
},
|
|
41
|
+
];
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
import type { D1Database } from "@cloudflare/workers-types";
|
|
5
|
+
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
6
|
+
import { exportRows, purgeBinding, type RetainingPurgeContribution } from "@pithy-sh/core/src/capability/purge";
|
|
7
|
+
import { EmailEvent } from "../data/emailEvent";
|
|
8
|
+
import { EmailJob } from "../data/emailJob";
|
|
9
|
+
import { EmailSuppression } from "../data/emailSuppression";
|
|
10
|
+
import { emailDatabase, emailSuppressionDatabase } from "../data/tables";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* What a person's purge means for `@pithy-sh/email` (#814): **nothing is erased, and the export says so and why.**
|
|
14
|
+
*
|
|
15
|
+
* A suppression has to outlive the person. It is the record that an address bounced, complained or asked not to be
|
|
16
|
+
* mailed, and the list is checked before every send: erase the row and the next send — a newsletter to an address
|
|
17
|
+
* that unsubscribed — goes out, because nothing remembers that it should not. So this contribution **retains**, and
|
|
18
|
+
* the log of mail sent to the address stays beside it as the delivery record a bounce or a complaint is read
|
|
19
|
+
* against. The purge records the step as retained with the basis below, and erases no row.
|
|
20
|
+
*
|
|
21
|
+
* **Found by address.** Email stores no user id: the suppression list and the log are keyed by the address, in
|
|
22
|
+
* `normalizeAddress`'s form. The step reads the account's address (`PurgeContext.address`); with none to read there
|
|
23
|
+
* is nothing to find.
|
|
24
|
+
*
|
|
25
|
+
* **Never a message's payload, and never a tracked link.** A job's payload is the template's variables, and a sign-in
|
|
26
|
+
* mail's variables are the link that signs the person in; a click event's URL can be that link. The export carries
|
|
27
|
+
* what was sent, when and how it went, and leaves both out.
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
/** The one sentence the purge records with this step. */
|
|
31
|
+
export const EMAIL_PURGE_SUMMARY = "Keeps the user's address on the suppression list, and the log of mail sent to it.";
|
|
32
|
+
|
|
33
|
+
/** Why, in the sentence the person is told. */
|
|
34
|
+
export const EMAIL_RETENTION_BASIS =
|
|
35
|
+
"Kept so your unsubscribe holds: the address stays on the list of addresses not to mail, with the record of what was sent to it.";
|
|
36
|
+
|
|
37
|
+
/** The user contribution `email()` declares, over its two D1 bindings. */
|
|
38
|
+
export function emailUserPurge(database = "DB", suppressions = "EMAIL_SUPPRESSIONS"): RetainingPurgeContribution {
|
|
39
|
+
return {
|
|
40
|
+
subject: "user",
|
|
41
|
+
summary: EMAIL_PURGE_SUMMARY,
|
|
42
|
+
retain: { basis: EMAIL_RETENTION_BASIS },
|
|
43
|
+
export: async (context) => {
|
|
44
|
+
const read = await context.address?.();
|
|
45
|
+
if (!read) return { suppressions: [], jobs: [], events: [] };
|
|
46
|
+
const address = normalizeAddress(read);
|
|
47
|
+
const log = emailDatabase(purgeBinding<D1Database>(context.env, database, "email"));
|
|
48
|
+
const list = emailSuppressionDatabase(purgeBinding<D1Database>(context.env, suppressions, "email"));
|
|
49
|
+
const [suppressed, jobs, events] = await Promise.all([
|
|
50
|
+
list.selectFrom("pithyEmailSuppressions").selectAll().where("email", "=", address).execute(),
|
|
51
|
+
log
|
|
52
|
+
.selectFrom("pithyEmailJobs")
|
|
53
|
+
.selectAll()
|
|
54
|
+
.where("recipientKey", "=", address)
|
|
55
|
+
.orderBy("createdAt")
|
|
56
|
+
.orderBy("id")
|
|
57
|
+
.execute(),
|
|
58
|
+
log
|
|
59
|
+
.selectFrom("pithyEmailEvents")
|
|
60
|
+
.selectAll()
|
|
61
|
+
.where("recipient", "=", address)
|
|
62
|
+
.orderBy("createdAt")
|
|
63
|
+
.orderBy("id")
|
|
64
|
+
.execute(),
|
|
65
|
+
]);
|
|
66
|
+
return {
|
|
67
|
+
suppressions: exportRows(suppressed.map((row) => EmailSuppression.parse(row))),
|
|
68
|
+
jobs: exportRows(
|
|
69
|
+
jobs.map((row) => {
|
|
70
|
+
const { payload: _variables, ...job } = EmailJob.parse(row);
|
|
71
|
+
return job;
|
|
72
|
+
}),
|
|
73
|
+
),
|
|
74
|
+
events: exportRows(
|
|
75
|
+
events.map((row) => {
|
|
76
|
+
const { linkUrl: _link, ...event } = EmailEvent.parse(row);
|
|
77
|
+
return event;
|
|
78
|
+
}),
|
|
79
|
+
),
|
|
80
|
+
};
|
|
81
|
+
},
|
|
82
|
+
};
|
|
83
|
+
}
|
package/src/send/enqueue.ts
CHANGED
|
@@ -2,10 +2,12 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
4
|
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
5
|
+
import type { ConsentReader, ConsentSubject } from "@pithy-sh/core/src/consent/reader";
|
|
5
6
|
import type { MeterCharge, MeterSubject } from "@pithy-sh/core/src/entitlement/meter";
|
|
6
7
|
import { isLocale } from "@pithy-sh/core/src/i18n/locale";
|
|
8
|
+
import { consentGate } from "../consent/consent";
|
|
7
9
|
import type { EmailJob } from "../data/emailJob";
|
|
8
|
-
import { EmailJob as EmailJobSchema } from "../data/emailJob";
|
|
10
|
+
import { EmailJob as EmailJobSchema, personalAddress } from "../data/emailJob";
|
|
9
11
|
import type { EmailJobStatus, SendMode, SuppressionReason } from "../data/enums";
|
|
10
12
|
import type { EmailDatabase, EmailSuppressionDatabase } from "../data/tables";
|
|
11
13
|
import { EmailInvalidPayloadError } from "../error/errors";
|
|
@@ -23,7 +25,7 @@ import { blockingSuppression } from "./suppression";
|
|
|
23
25
|
* `scheduled` and `timezone` jobs are left for the every-minute scheduler to pick up. The payload is
|
|
24
26
|
* validated against the template schema here, so a bad call fails at enqueue, not mid-send.
|
|
25
27
|
*
|
|
26
|
-
* **Suppression is consulted here too, and no caller asks for it
|
|
28
|
+
* **Suppression is consulted here too, and no caller asks for it**. A blocked
|
|
27
29
|
* recipient never becomes a queued send: the row is born `suppressed`, no Workflow is started, and the
|
|
28
30
|
* reason comes back on the result. The point is not a second gate — `runSend` is and stays the
|
|
29
31
|
* authority, because whether an address is blocked is a question about the instant of sending and a
|
|
@@ -42,7 +44,7 @@ import { blockingSuppression } from "./suppression";
|
|
|
42
44
|
* The Workflow binding used to start a send (Cloudflare `Workflow.create`). At enqueue it sends a batch
|
|
43
45
|
* of one; the scheduler's fan-out starts one instance per batch through the same binding.
|
|
44
46
|
*
|
|
45
|
-
* `id` names the instance being created, and **every dispatcher passes one
|
|
47
|
+
* `id` names the instance being created, and **every dispatcher passes one**: the
|
|
46
48
|
* scheduler passes its batch's, an enqueue passes the one it just stamped on the row, and a retry passes
|
|
47
49
|
* the one it minted to replace the failed batch's. It is optional here only because the platform allows
|
|
48
50
|
* omitting it, and omitting it is what made an immediate send unattributable to any instance — so the
|
|
@@ -88,7 +90,7 @@ export interface EnqueueInput {
|
|
|
88
90
|
/**
|
|
89
91
|
* What this message is *about*, when the template id does not say it on its own.
|
|
90
92
|
*
|
|
91
|
-
* The discriminator for a template that carries more than one kind of message
|
|
93
|
+
* The discriminator for a template that carries more than one kind of message.
|
|
92
94
|
* `sentSince` matches on it, so a caller deciding whether to send — or whether to send a *correction* —
|
|
93
95
|
* can tell two messages apart that share a template and a recipient. Opaque: nothing here parses it,
|
|
94
96
|
* renders it, or puts it on a header or a link.
|
|
@@ -132,6 +134,14 @@ export interface EnqueueInput {
|
|
|
132
134
|
* enqueue past the period's quota throws `payments/quota_exceeded` and writes no job.
|
|
133
135
|
*/
|
|
134
136
|
subject?: MeterSubject;
|
|
137
|
+
/**
|
|
138
|
+
* Whose consent this message is sent under, when `@pithy-sh/consent` is composed: the recipient's account,
|
|
139
|
+
* or the visitor id they consented under. A `marketing` template is sent only to a subject consenting to
|
|
140
|
+
* `email.marketing`, and opens and clicks are tracked only for one consenting to `email.tracking`. Omitted, a
|
|
141
|
+
* marketing message is withheld and nothing is tracked, because nobody's consent can be shown. Transactional mail
|
|
142
|
+
* is never gated, and without consent composed this is ignored.
|
|
143
|
+
*/
|
|
144
|
+
consentSubject?: ConsentSubject;
|
|
135
145
|
}
|
|
136
146
|
|
|
137
147
|
/** Dependencies enqueue needs: the database, the from identity, optional send-Workflow binding, time, ids. */
|
|
@@ -165,12 +175,16 @@ export interface EnqueueDeps {
|
|
|
165
175
|
* request's env. Absent when no provider is composed, and then nothing is counted.
|
|
166
176
|
*/
|
|
167
177
|
meter?: (charge: MeterCharge) => Promise<void>;
|
|
178
|
+
/**
|
|
179
|
+
* The composed consent reader, or absent when no consent capability is composed — and then nothing is
|
|
180
|
+
* gated.
|
|
181
|
+
*/
|
|
182
|
+
consent?: ConsentReader | null;
|
|
168
183
|
now: Date;
|
|
169
184
|
/** Generate a job id (a UUID in production). */
|
|
170
185
|
newId: () => string;
|
|
171
186
|
/**
|
|
172
|
-
* Mint the id of the batch this enqueue dispatches — **the send Workflow instance's id
|
|
173
|
-
* (pithy-sh/pithy#342). Defaults to {@link mintBatchId}; injected only so a test can name it.
|
|
187
|
+
* Mint the id of the batch this enqueue dispatches — **the send Workflow instance's id**. Defaults to {@link mintBatchId}; injected only so a test can name it.
|
|
174
188
|
*/
|
|
175
189
|
newBatchId?: () => string;
|
|
176
190
|
}
|
|
@@ -183,7 +197,7 @@ export interface EnqueueResult {
|
|
|
183
197
|
*
|
|
184
198
|
* `pending` and `scheduled` both mean a send is on its way. `suppressed` means the address is
|
|
185
199
|
* blocked. **`undispatched` means this composition binds no send Workflow**, so nothing was started
|
|
186
|
-
* and nothing is coming while it stays that way
|
|
200
|
+
* and nothing is coming while it stays that way: a caller that renders "check
|
|
187
201
|
* your inbox" off it is reporting a delivery that cannot happen. It is the one status here that
|
|
188
202
|
* describes the *deployment* rather than the message — and the scheduler drains those rows once a
|
|
189
203
|
* host exists, so it is not the end of the job.
|
|
@@ -198,9 +212,15 @@ export interface EnqueueResult {
|
|
|
198
212
|
* operator's next move depends on.
|
|
199
213
|
*/
|
|
200
214
|
suppressionReason?: SuppressionReason;
|
|
215
|
+
/**
|
|
216
|
+
* The consent purpose that withheld this message, when consent is composed and the subject does not hold it —
|
|
217
|
+
* `email.marketing`. The row is born `suppressed` and nothing is sent. Absent for every message consent
|
|
218
|
+
* did not withhold.
|
|
219
|
+
*/
|
|
220
|
+
consentWithheld?: string;
|
|
201
221
|
/**
|
|
202
222
|
* The **enqueue-time** render — the sentence this call wrote to `pithy_email_jobs.subject`, in the
|
|
203
|
-
* recipient's language, and the value the row is born with
|
|
223
|
+
* recipient's language, and the value the row is born with.
|
|
204
224
|
*
|
|
205
225
|
* **For the caller that has to say what it queued.** Enqueuing is what a surface does; auditing it is
|
|
206
226
|
* what a surface with an administrative trail also does. Without this, that caller had to render the
|
|
@@ -271,9 +291,18 @@ export async function enqueueEmail(deps: EnqueueDeps, input: EnqueueInput): Prom
|
|
|
271
291
|
* agreeing is what makes a hard bounce withhold an invitation while an unsubscribe does not. A caller
|
|
272
292
|
* cannot influence this and is not asked to: it is the template's own declaration.
|
|
273
293
|
*/
|
|
274
|
-
const
|
|
294
|
+
const suppressed: SuppressionReason | null = deps.suppressionDb
|
|
275
295
|
? await blockingSuppression(deps.suppressionDb, input.to, deps.now, templateKind(input.template))
|
|
276
296
|
: null;
|
|
297
|
+
/**
|
|
298
|
+
* What consent allows, when it is composed: a marketing message to a subject not consenting to it is
|
|
299
|
+
* withheld like a suppressed one, and tracking runs only for a subject consenting to it. Transactional mail is
|
|
300
|
+
* never withheld. With no consent composed the gate passes everything.
|
|
301
|
+
*/
|
|
302
|
+
const marketing = template.category === "marketing";
|
|
303
|
+
const gate = await consentGate(deps.consent, input.consentSubject, marketing);
|
|
304
|
+
const withheld = suppressed === null ? gate.withheld : null;
|
|
305
|
+
const blocked = suppressed !== null || withheld !== null;
|
|
277
306
|
// The match key, on the same normalization the suppression list is written and read under. The row
|
|
278
307
|
// keeps the address as the caller typed it in `toAddress` — an operator diagnosing a send needs the
|
|
279
308
|
// string that was actually addressed — and carries this beside it as `recipientKey`, which is what
|
|
@@ -286,7 +315,7 @@ export async function enqueueEmail(deps: EnqueueDeps, input: EnqueueInput): Prom
|
|
|
286
315
|
// else is left for the scheduler to claim.
|
|
287
316
|
const sender = !blocked && mode === "immediate" ? deps.sender : undefined;
|
|
288
317
|
/**
|
|
289
|
-
* An immediate job with nothing to dispatch it on
|
|
318
|
+
* An immediate job with nothing to dispatch it on.
|
|
290
319
|
*
|
|
291
320
|
* A missing binding is a **configuration fact known at compose time**, not a transient failure, and
|
|
292
321
|
* the two used to be recorded identically: both left the row `pending` and told the caller "on its
|
|
@@ -309,7 +338,7 @@ export async function enqueueEmail(deps: EnqueueDeps, input: EnqueueInput): Prom
|
|
|
309
338
|
const status: EmailJobStatus = blocked ? "suppressed" : undispatchable ? "undispatched" : scheduled;
|
|
310
339
|
/**
|
|
311
340
|
* The batch this enqueue is about to start — named here, before the row exists, because the row has to
|
|
312
|
-
* carry it
|
|
341
|
+
* carry it.
|
|
313
342
|
*
|
|
314
343
|
* Without it the row is born naming nobody, and a row naming nobody is stranded by definition: the
|
|
315
344
|
* scheduler's safety net claims any `pending` job older than `graceMs` and starts a *second* send
|
|
@@ -337,11 +366,10 @@ export async function enqueueEmail(deps: EnqueueDeps, input: EnqueueInput): Prom
|
|
|
337
366
|
await deps.meter({ subject: input.subject, meter: "emails", amount: 1, now: deps.now });
|
|
338
367
|
}
|
|
339
368
|
|
|
340
|
-
const marketing = template.category === "marketing";
|
|
341
369
|
const job: EmailJob = {
|
|
342
370
|
id: deps.newId(),
|
|
343
|
-
toAddress: input.to,
|
|
344
|
-
recipientKey: recipient,
|
|
371
|
+
toAddress: personalAddress(input.to),
|
|
372
|
+
recipientKey: personalAddress(recipient),
|
|
345
373
|
fromAddress: deps.fromAddress,
|
|
346
374
|
fromName: deps.fromName,
|
|
347
375
|
subject,
|
|
@@ -368,17 +396,19 @@ export async function enqueueEmail(deps: EnqueueDeps, input: EnqueueInput): Prom
|
|
|
368
396
|
// The same shape as `renderLocale` on the send side, and for the same reason.
|
|
369
397
|
locale: isLocale(input.locale ?? "") ? (input.locale ?? null) : null,
|
|
370
398
|
correlation: input.correlation ?? null,
|
|
371
|
-
openTracking: input.openTracking ?? marketing,
|
|
372
|
-
clickTracking: input.clickTracking ?? marketing,
|
|
399
|
+
openTracking: (input.openTracking ?? marketing) && gate.tracking,
|
|
400
|
+
clickTracking: (input.clickTracking ?? marketing) && gate.tracking,
|
|
373
401
|
messageId: null,
|
|
374
402
|
// The same sentence `runSend` writes when it skips one, so the send log reads the same whichever
|
|
375
403
|
// pass caught it — and, for the undispatchable row, the one sentence that says why it stopped
|
|
376
404
|
// here. The status is the state; this column is what an operator reads next to it.
|
|
377
|
-
error:
|
|
378
|
-
? `recipient suppressed: ${
|
|
379
|
-
:
|
|
380
|
-
?
|
|
381
|
-
:
|
|
405
|
+
error: suppressed
|
|
406
|
+
? `recipient suppressed: ${suppressed}`
|
|
407
|
+
: withheld
|
|
408
|
+
? `no consent: ${withheld}`
|
|
409
|
+
: undispatchable
|
|
410
|
+
? "no EMAIL_SENDER binding: this composition can start no send Workflow"
|
|
411
|
+
: null,
|
|
382
412
|
bounceCode: null,
|
|
383
413
|
bounceType: null,
|
|
384
414
|
replyTo: input.replyTo ?? null,
|
|
@@ -394,9 +424,17 @@ export async function enqueueEmail(deps: EnqueueDeps, input: EnqueueInput): Prom
|
|
|
394
424
|
// A withheld message is on the record as an event, not merely as a status — the send log's history is
|
|
395
425
|
// what an operator reads to find out that an advisory reached nobody, and a row with no event in it
|
|
396
426
|
// looks exactly like a job still waiting its turn.
|
|
397
|
-
if (
|
|
398
|
-
await recordEvent(deps.db, { jobId: job.id, recipient, type: "suppressed", detail:
|
|
399
|
-
return { jobId: job.id, status, subject, suppressionReason:
|
|
427
|
+
if (suppressed) {
|
|
428
|
+
await recordEvent(deps.db, { jobId: job.id, recipient, type: "suppressed", detail: suppressed }, deps.now);
|
|
429
|
+
return { jobId: job.id, status, subject, suppressionReason: suppressed };
|
|
430
|
+
}
|
|
431
|
+
if (withheld) {
|
|
432
|
+
await recordEvent(
|
|
433
|
+
deps.db,
|
|
434
|
+
{ jobId: job.id, recipient, type: "suppressed", detail: `consent:${withheld}` },
|
|
435
|
+
deps.now,
|
|
436
|
+
);
|
|
437
|
+
return { jobId: job.id, status, subject, consentWithheld: withheld };
|
|
400
438
|
}
|
|
401
439
|
|
|
402
440
|
// Immediate sends start the Workflow now for lowest latency, under the id the row already carries —
|
|
@@ -136,6 +136,47 @@ export const EMAIL_ES: MessageCatalog = {
|
|
|
136
136
|
"Tu cuenta de {app} y sus datos se borraron el {purgedOn}. No se puede deshacer.",
|
|
137
137
|
"email/deletion_complete.last": "Es el último correo que recibirá esta cuenta.",
|
|
138
138
|
|
|
139
|
+
// --- Administración de la pertenencia ---
|
|
140
|
+
"email/organization_member_added.subject": "Te han añadido a {organization}",
|
|
141
|
+
"email/organization_member_added.heading": "Te han añadido a una organización",
|
|
142
|
+
"email/organization_member_added.body": "te han añadido a {organization} en {app}, con la función {role}.",
|
|
143
|
+
"email/organization_member_added.text_body": "Te han añadido a {organization} en {app}, con la función {role}.",
|
|
144
|
+
"email/organization_member_removed.subject": "Te han quitado de {organization}",
|
|
145
|
+
"email/organization_member_removed.heading": "Te han quitado de una organización",
|
|
146
|
+
"email/organization_member_removed.body": "te han quitado de {organization} en {app}. Ya no puedes actuar en ella.",
|
|
147
|
+
"email/organization_member_removed.text_body":
|
|
148
|
+
"Te han quitado de {organization} en {app}. Ya no puedes actuar en ella.",
|
|
149
|
+
"email/organization_ownership_transferred.subject": "Ahora eres titular de {organization}",
|
|
150
|
+
"email/organization_ownership_transferred.heading": "Ahora eres titular de una organización",
|
|
151
|
+
"email/organization_ownership_transferred.body":
|
|
152
|
+
"ahora eres titular de {organization} en {app}. La administras y respondes por ella.",
|
|
153
|
+
"email/organization_ownership_transferred.text_body":
|
|
154
|
+
"Ahora eres titular de {organization} en {app}. La administras y respondes por ella.",
|
|
155
|
+
"email/organization_member.contact": "Si no lo esperabas, responde a este correo.",
|
|
156
|
+
|
|
157
|
+
// --- Ciclo de vida de la organización ---
|
|
158
|
+
"email/organization_suspended.subject": "{organization} está suspendida",
|
|
159
|
+
"email/organization_suspended.heading": "Tu organización está suspendida",
|
|
160
|
+
"email/organization_suspended.body":
|
|
161
|
+
"{organization} en {app} está suspendida. Nadie puede actuar en ella hasta que se restablezca. Tu propia cuenta no se ve afectada.",
|
|
162
|
+
"email/organization_suspended.text_body":
|
|
163
|
+
"{organization} en {app} está suspendida. Nadie puede actuar en ella hasta que se restablezca. Tu propia cuenta no se ve afectada.",
|
|
164
|
+
"email/organization_suspended.reason": "El motivo indicado: {reason}",
|
|
165
|
+
"email/organization_suspended.until": "Termina el {until}.",
|
|
166
|
+
"email/organization_reinstated.subject": "{organization} está restablecida",
|
|
167
|
+
"email/organization_reinstated.heading": "Tu organización está restablecida",
|
|
168
|
+
"email/organization_reinstated.body":
|
|
169
|
+
"{organization} en {app} está restablecida. Sus miembros pueden volver a actuar en ella.",
|
|
170
|
+
"email/organization_reinstated.text_body":
|
|
171
|
+
"{organization} en {app} está restablecida. Sus miembros pueden volver a actuar en ella.",
|
|
172
|
+
"email/organization_deletion_scheduled.subject": "{organization} está eliminada",
|
|
173
|
+
"email/organization_deletion_scheduled.heading": "Tu organización está eliminada",
|
|
174
|
+
"email/organization_deletion_scheduled.body":
|
|
175
|
+
"{organization} en {app} está eliminada. Nadie puede actuar en ella, y sus datos se borrarán el {purgeOn}.",
|
|
176
|
+
"email/organization_deletion_scheduled.text_body":
|
|
177
|
+
"{organization} en {app} está eliminada. Nadie puede actuar en ella, y sus datos se borrarán el {purgeOn}.",
|
|
178
|
+
"email/organization_deletion_scheduled.contact": "Para conservarla, responde a este correo antes del {purgeOn}.",
|
|
179
|
+
|
|
139
180
|
// --- leadCapture ---
|
|
140
181
|
"email/lead_capture.subject": "Tu descarga: {asset}",
|
|
141
182
|
"email/lead_capture.heading": "Tu descarga está lista",
|
|
@@ -44,14 +44,14 @@ import { EMAIL_ES } from "./messages.es";
|
|
|
44
44
|
*
|
|
45
45
|
* ## Only the kit's own copy
|
|
46
46
|
*
|
|
47
|
-
*
|
|
47
|
+
* Seventeen templates are here. The five whose words arrive as payload — `testerNudge`, `supportReply`,
|
|
48
48
|
* `operationalNotice`, `newsletter`, `marketingCampaign` — are the adopter's copy, chosen by a human
|
|
49
49
|
* for one message, and a catalog cannot translate a sentence it has never seen. Their **shell** still
|
|
50
50
|
* follows the job's locale (the severity word, the footer, the document's `lang` and `dir`), so a
|
|
51
51
|
* notice at locale `es` reads its severity in Spanish and its summary in whatever the caller wrote.
|
|
52
52
|
*/
|
|
53
53
|
|
|
54
|
-
/** The kit's English for every string the
|
|
54
|
+
/** The kit's English for every string the seventeen kit-authored templates and the shared shell render. */
|
|
55
55
|
const EMAIL_EN: MessageCatalog = {
|
|
56
56
|
// --- The shared shell ---
|
|
57
57
|
// The greeting is two keys rather than one with an optional placeholder, because a language that
|
|
@@ -123,7 +123,7 @@ const EMAIL_EN: MessageCatalog = {
|
|
|
123
123
|
"email/password_changed.text_body":
|
|
124
124
|
"Your account credentials were changed on {when}. If this wasn't you, contact support:",
|
|
125
125
|
|
|
126
|
-
// --- The account lifecycle
|
|
126
|
+
// --- The account lifecycle ---
|
|
127
127
|
// Each says what happened, what it means, and who to answer. The answer is a reply: the mail comes from the
|
|
128
128
|
// adopter's own address, so a reply reaches the people who can act on it.
|
|
129
129
|
"email/account_suspended.subject": "Your {app} account is suspended",
|
|
@@ -157,6 +157,50 @@ const EMAIL_EN: MessageCatalog = {
|
|
|
157
157
|
"Your {app} account and its data were erased on {purgedOn}. This cannot be undone.",
|
|
158
158
|
"email/deletion_complete.last": "This is the last email this account will receive.",
|
|
159
159
|
|
|
160
|
+
// --- Membership administration ---
|
|
161
|
+
// An operator changed somebody's membership. Each names the organization, because a person in two
|
|
162
|
+
// accounts has to know which one changed, and closes on who to answer.
|
|
163
|
+
"email/organization_member_added.subject": "You were added to {organization}",
|
|
164
|
+
"email/organization_member_added.heading": "You were added to an organization",
|
|
165
|
+
"email/organization_member_added.body": "you were added to {organization} on {app}, as {role}.",
|
|
166
|
+
"email/organization_member_added.text_body": "You were added to {organization} on {app}, as {role}.",
|
|
167
|
+
"email/organization_member_removed.subject": "You were removed from {organization}",
|
|
168
|
+
"email/organization_member_removed.heading": "You were removed from an organization",
|
|
169
|
+
"email/organization_member_removed.body":
|
|
170
|
+
"you were removed from {organization} on {app}. You can no longer act in it.",
|
|
171
|
+
"email/organization_member_removed.text_body":
|
|
172
|
+
"You were removed from {organization} on {app}. You can no longer act in it.",
|
|
173
|
+
"email/organization_ownership_transferred.subject": "You now own {organization}",
|
|
174
|
+
"email/organization_ownership_transferred.heading": "You now own an organization",
|
|
175
|
+
"email/organization_ownership_transferred.body":
|
|
176
|
+
"you are now the owner of {organization} on {app}. You administer it, and you answer for it.",
|
|
177
|
+
"email/organization_ownership_transferred.text_body":
|
|
178
|
+
"You are now the owner of {organization} on {app}. You administer it, and you answer for it.",
|
|
179
|
+
"email/organization_member.contact": "If you did not expect this, reply to this email.",
|
|
180
|
+
|
|
181
|
+
// --- The organization lifecycle ---
|
|
182
|
+
// To an owner, when an operator acts on the organization itself. Each names it, and says the owner's own
|
|
183
|
+
// account is not what changed.
|
|
184
|
+
"email/organization_suspended.subject": "{organization} is suspended",
|
|
185
|
+
"email/organization_suspended.heading": "Your organization is suspended",
|
|
186
|
+
"email/organization_suspended.body":
|
|
187
|
+
"{organization} on {app} is suspended. Nobody can act in it until it is reinstated. Your own account is not affected.",
|
|
188
|
+
"email/organization_suspended.text_body":
|
|
189
|
+
"{organization} on {app} is suspended. Nobody can act in it until it is reinstated. Your own account is not affected.",
|
|
190
|
+
"email/organization_suspended.reason": "The reason given: {reason}",
|
|
191
|
+
"email/organization_suspended.until": "It ends on {until}.",
|
|
192
|
+
"email/organization_reinstated.subject": "{organization} is reinstated",
|
|
193
|
+
"email/organization_reinstated.heading": "Your organization is reinstated",
|
|
194
|
+
"email/organization_reinstated.body": "{organization} on {app} is reinstated. Its members can act in it again.",
|
|
195
|
+
"email/organization_reinstated.text_body": "{organization} on {app} is reinstated. Its members can act in it again.",
|
|
196
|
+
"email/organization_deletion_scheduled.subject": "{organization} is deleted",
|
|
197
|
+
"email/organization_deletion_scheduled.heading": "Your organization is deleted",
|
|
198
|
+
"email/organization_deletion_scheduled.body":
|
|
199
|
+
"{organization} on {app} is deleted. Nobody can act in it, and its data will be erased on {purgeOn}.",
|
|
200
|
+
"email/organization_deletion_scheduled.text_body":
|
|
201
|
+
"{organization} on {app} is deleted. Nobody can act in it, and its data will be erased on {purgeOn}.",
|
|
202
|
+
"email/organization_deletion_scheduled.contact": "To keep it, reply to this email before {purgeOn}.",
|
|
203
|
+
|
|
160
204
|
// --- leadCapture ---
|
|
161
205
|
"email/lead_capture.subject": "Your download: {asset}",
|
|
162
206
|
"email/lead_capture.heading": "Your download is ready",
|
|
@@ -171,8 +215,7 @@ const EMAIL_EN: MessageCatalog = {
|
|
|
171
215
|
* Every language this capability's own copy is written in.
|
|
172
216
|
*
|
|
173
217
|
* **Bundled, not stamped.** The send Worker is deployed with this map inside it, so adding a language
|
|
174
|
-
* to the kit costs an adopter a package upgrade and no configuration at all
|
|
175
|
-
* #442. What still travels as a variable is the adopter's diff against this: usually nothing, and at
|
|
218
|
+
* to the kit costs an adopter a package upgrade and no configuration at all. What still travels as a variable is the adopter's diff against this: usually nothing, and at
|
|
176
219
|
* most the sentences they changed.
|
|
177
220
|
*/
|
|
178
221
|
export const EMAIL_MESSAGES: LocaleCatalogs = { en: EMAIL_EN, es: EMAIL_ES };
|
|
@@ -198,12 +241,10 @@ function languageOf(tag: string): string | null {
|
|
|
198
241
|
/**
|
|
199
242
|
* This package's own copy for `locale`, reduced to the language when the region was not written for.
|
|
200
243
|
*
|
|
201
|
-
* **The reduction has to happen here too, and not only over the stamped catalogs.**
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
*
|
|
205
|
-
* exact-tag lookup on `es-AR` answered `undefined` — so a reader whose `pithy_auth_users.locale` is
|
|
206
|
-
* `es-AR` or `es-MX` got an English letter from a project that ships Spanish.
|
|
244
|
+
* **The reduction has to happen here too, and not only over the stamped catalogs.** With the kit's copy
|
|
245
|
+
* bundled here, the stamped catalog is empty for a project that overrode nothing, so an exact-tag
|
|
246
|
+
* lookup on `es-AR` alone would send a reader whose `pithy_auth_users.locale` is `es-AR` or `es-MX` an
|
|
247
|
+
* English letter from a project that ships Spanish.
|
|
207
248
|
*/
|
|
208
249
|
function bundledFor(locale: string): MessageCatalog | undefined {
|
|
209
250
|
const language = languageOf(locale);
|