@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.
Files changed (59) hide show
  1. package/README.md +8 -0
  2. package/dist/capability.d.ts +2 -2
  3. package/dist/capability.d.ts.map +1 -1
  4. package/dist/capability.js +23 -2
  5. package/dist/consent/consent.d.ts +57 -0
  6. package/dist/consent/consent.d.ts.map +1 -0
  7. package/dist/consent/consent.js +135 -0
  8. package/dist/data/emailEvent.d.ts +1 -1
  9. package/dist/data/emailEvent.d.ts.map +1 -1
  10. package/dist/data/emailEvent.js +2 -1
  11. package/dist/data/emailJob.d.ts +6 -2
  12. package/dist/data/emailJob.d.ts.map +1 -1
  13. package/dist/data/emailJob.js +8 -3
  14. package/dist/data/emailSuppression.d.ts +1 -1
  15. package/dist/data/emailSuppression.d.ts.map +1 -1
  16. package/dist/data/emailSuppression.js +2 -1
  17. package/dist/data/tables.d.ts +4 -4
  18. package/dist/http/guards.d.ts +2 -2
  19. package/dist/http/guards.d.ts.map +1 -1
  20. package/dist/http/guards.js +12 -0
  21. package/dist/processing/activities.d.ts +9 -0
  22. package/dist/processing/activities.d.ts.map +1 -0
  23. package/dist/processing/activities.js +40 -0
  24. package/dist/purge/contribution.d.ts +27 -0
  25. package/dist/purge/contribution.d.ts.map +1 -0
  26. package/dist/purge/contribution.js +67 -0
  27. package/dist/send/enqueue.d.ts +26 -7
  28. package/dist/send/enqueue.d.ts.map +1 -1
  29. package/dist/send/enqueue.js +36 -13
  30. package/dist/templates/messages.d.ts +1 -2
  31. package/dist/templates/messages.d.ts.map +1 -1
  32. package/dist/templates/messages.es.d.ts.map +1 -1
  33. package/dist/templates/messages.es.js +28 -0
  34. package/dist/templates/messages.js +35 -10
  35. package/dist/templates/precompiled.generated.d.ts +124 -0
  36. package/dist/templates/precompiled.generated.d.ts.map +1 -1
  37. package/dist/templates/precompiled.generated.js +1618 -0
  38. package/dist/templates/registry.d.ts.map +1 -1
  39. package/dist/templates/registry.js +106 -0
  40. package/dist/templates/samples.d.ts.map +1 -1
  41. package/dist/templates/samples.js +28 -0
  42. package/dist/version.generated.d.ts +1 -1
  43. package/dist/version.generated.js +1 -1
  44. package/package.json +3 -3
  45. package/src/capability.ts +33 -7
  46. package/src/consent/consent.ts +183 -0
  47. package/src/data/emailEvent.ts +2 -1
  48. package/src/data/emailJob.ts +21 -8
  49. package/src/data/emailSuppression.ts +2 -1
  50. package/src/http/guards.ts +14 -2
  51. package/src/processing/activities.ts +41 -0
  52. package/src/purge/contribution.ts +83 -0
  53. package/src/send/enqueue.ts +62 -24
  54. package/src/templates/messages.es.ts +41 -0
  55. package/src/templates/messages.ts +52 -11
  56. package/src/templates/precompiled.generated.ts +551 -0
  57. package/src/templates/registry.ts +159 -0
  58. package/src/templates/samples.ts +11 -0
  59. package/src/version.generated.ts +1 -1
@@ -1,7 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
- import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
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): AdminRoute[] {
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
+ }
@@ -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** (pithy-sh/pithy#355). A blocked
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** (pithy-sh/pithy#342): the
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 (pithy-sh/pithy#382).
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 (pithy-sh/pithy#410): a caller that renders "check
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 (pithy-sh/pithy#443).
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 blocked: SuppressionReason | null = deps.suppressionDb
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 (pithy-sh/pithy#410).
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 (pithy-sh/pithy#342).
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: blocked
378
- ? `recipient suppressed: ${blocked}`
379
- : undispatchable
380
- ? "no EMAIL_SENDER binding: this composition can start no send Workflow"
381
- : null,
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 (blocked) {
398
- await recordEvent(deps.db, { jobId: job.id, recipient, type: "suppressed", detail: blocked }, deps.now);
399
- return { jobId: job.id, status, subject, suppressionReason: blocked };
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
- * Eleven templates are here. The five whose words arrive as payload — `testerNudge`, `supportReply`,
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 eleven kit-authored templates and the shared shell render. */
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 (#620) ---
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 — which is the whole of
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.** It did not, and
202
- * that was a regression the moment #442 bundled the kit's translations: the stamped catalog used to
203
- * *be* the kit's Spanish, so reducing `es-AR` to `es` over it found the words. With the kit's copy
204
- * bundled here instead, the stamped catalog is empty for a project that overrode nothing, and an
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);