@pithy-sh/email 0.7.0 → 0.8.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.
Files changed (46) 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.js +7 -10
  33. package/dist/version.generated.d.ts +1 -1
  34. package/dist/version.generated.js +1 -1
  35. package/package.json +3 -3
  36. package/src/capability.ts +33 -7
  37. package/src/consent/consent.ts +183 -0
  38. package/src/data/emailEvent.ts +2 -1
  39. package/src/data/emailJob.ts +21 -8
  40. package/src/data/emailSuppression.ts +2 -1
  41. package/src/http/guards.ts +14 -2
  42. package/src/processing/activities.ts +41 -0
  43. package/src/purge/contribution.ts +83 -0
  44. package/src/send/enqueue.ts +62 -24
  45. package/src/templates/messages.ts +10 -13
  46. package/src/version.generated.ts +1 -1
package/README.md CHANGED
@@ -12,6 +12,14 @@ pithy add email
12
12
 
13
13
  _Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
14
14
 
15
+ ## Consent
16
+
17
+ Email declares two consent purposes: `email.marketing` and `email.tracking`. With [`@pithy-sh/consent`](../consent/README.md) composed, a `marketing` template is sent only to a subject consenting to marketing, and opens and clicks are tracked only for one consenting to tracking. Pass the subject as `consentSubject` when you enqueue. A message with no subject is withheld if marketing and untracked either way. Transactional mail is never gated. A withdrawal from marketing suppresses the address for elective mail, permanently, so it also holds mail already scheduled; granting marketing again lifts that suppression and no other, so a bounce, a complaint or an unsubscribe link stands. A withdrawal from tracking stops tracking mail already queued. Without consent composed, email behaves as it always has, and `pithy doctor` says tracking runs with no consent record behind it.
18
+
19
+ ## A person's data
20
+
21
+ **Retained.** When an account is purged, email erases nothing: *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.* The purge records the step as retained with that basis, and an export hands back the address's suppression and its mail log — never a message's variables or a tracked link. See [`@pithy-sh/auth`'s account lifecycle](../auth/docs/account-lifecycle.md#what-each-capability-does-with-a-persons-rows).
22
+
15
23
  ## License
16
24
 
17
25
  MIT — adopter-side app value. The root `LICENSE` covers it.
@@ -14,7 +14,7 @@ import { type EmailTheme } from "./templates/theme";
14
14
  * global suppression database. A consumer (e.g. `@pithy-sh/auth`) forwards its worker env; it never
15
15
  * names these bindings itself.
16
16
  *
17
- * **`EMAIL_SUPPRESSIONS` is on this list, and that is the whole of pithy-sh/pithy#355.** The wiring is
17
+ * **`EMAIL_SUPPRESSIONS` is on this list.** The wiring is
18
18
  * not the adopter's problem: the capability declares the binding, `pithy add email` provisions it,
19
19
  * `enqueue` reads it off the env, and no consumer config, route option, or constant names it. What an
20
20
  * adopter *may* do — because it is their database — is ask for it back through
@@ -120,7 +120,7 @@ export interface EmailCapability extends Capability {
120
120
  enqueue: (env: EmailEnqueueEnv, input: EnqueueInput) => Promise<EnqueueResult>;
121
121
  /**
122
122
  * The suppression list, from a request env — **it is the adopter's database, and this is how they open
123
- * it** (pithy-sh/pithy#355).
123
+ * it**.
124
124
  *
125
125
  * Nobody has to call this to be protected: `enqueue` consults the list on its own and `runSend`
126
126
  * refuses a blocked recipient regardless. This exists for the adopter who genuinely wants to look —
@@ -1 +1 @@
1
- {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAI7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EACL,KAAK,wBAAwB,EAM9B,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAgB,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EAAe,KAAK,UAAU,EAAgB,MAAM,mBAAmB,CAAC;AAI/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,EAAE,EAAE,UAAU,CAAC;IACf;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,UAAU,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,kGAAkG;AAClG,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,WAAW,EAAE,mBAAmB,CAAC;IACjC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/E;;;;;;;;;;;;;OAaG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,wBAAwB,CAAC;IACjE;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,MAAM,cAAc,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAoO/D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
1
+ {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAK7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EACL,KAAK,wBAAwB,EAM9B,MAAM,eAAe,CAAC;AAOvB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI1D,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAgB,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EAAe,KAAK,UAAU,EAAgB,MAAM,mBAAmB,CAAC;AAI/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,EAAE,EAAE,UAAU,CAAC;IACf;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,UAAU,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,kGAAkG;AAClG,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,WAAW,EAAE,mBAAmB,CAAC;IACjC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/E;;;;;;;;;;;;;OAaG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,wBAAwB,CAAC;IACjE;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,MAAM,cAAc,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CA0P/D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { emailDatabase, emailSuppressionDatabase, emailSuppressionTables, emailSuppressionsRetainedTables, emailTables } from "./data/tables.js";
4
4
  import { createBounceHandler } from "./bounce/handler.js";
5
+ import { EMAIL_CONSENT_PURPOSES, emailConsentGranted, emailConsentWithdrawn } from "./consent/consent.js";
5
6
  import { emailSigningRegistry } from "./crypto/signingKey.js";
6
7
  import { EMAIL_MESSAGES, kitEmailLayers } from "./templates/messages.js";
7
8
  import { CustomTheme, resolveTheme } from "./templates/theme.js";
@@ -11,15 +12,18 @@ import { emailSenderBinding } from "./send/senderBinding.js";
11
12
  import { registerEmailAdminRoutes } from "./http/routes.js";
12
13
  import { email_0001_init } from "./migrations/0001_init.js";
13
14
  import { email_0001_suppressions } from "./migrations/0001_suppressions.js";
15
+ import { EMAIL_PROCESSING } from "./processing/activities.js";
14
16
  import { DevMailDelivery } from "./provision/devDelivery.js";
15
17
  import { emailHostCatalogs } from "./provision/hostCatalogs.js";
16
18
  import { emailSettings } from "./provision/settingsCheck.js";
19
+ import { emailUserPurge } from "./purge/contribution.js";
17
20
  import { enqueueEmail } from "./send/enqueue.js";
18
21
  import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated.js";
19
22
  import { EmailScheduleParams, EmailSendParams } from "./workflows/params.js";
20
23
  import { z } from "zod";
21
24
  import { defineCapability } from "@pithy-sh/core/src/capability/capability";
22
25
  import { pithyCommandOf } from "@pithy-sh/core/src/cli/command";
26
+ import { composedConsent } from "@pithy-sh/core/src/consent/reader";
23
27
  import { composedUsageMeter } from "@pithy-sh/core/src/entitlement/meter";
24
28
  import { InternalError } from "@pithy-sh/core/src/error/pithyError";
25
29
  //#region src/capability.ts
@@ -87,6 +91,11 @@ function email(config) {
87
91
  * exactly as it always was: nothing is counted and nothing is refused.
88
92
  */
89
93
  let meter;
94
+ /**
95
+ * Every composed capability, kept by `compose` so an enqueue can find the consent reader over its own env.
96
+ * Empty until then, which is a composition with no consent: nothing is gated.
97
+ */
98
+ let composition = [];
90
99
  const capability = defineCapability({
91
100
  name: "email",
92
101
  version: PACKAGE_VERSION,
@@ -97,7 +106,7 @@ function email(config) {
97
106
  * This capability's own copy — the seven templates whose words the kit owns, plus the shell's
98
107
  * severity vocabulary and its opt-out link. All under `email/`, which `composeMessages` enforces.
99
108
  *
100
- * **In every language it is written in, not English alone (#442).** The send Worker is a separate
109
+ * **In every language it is written in, not English alone.** The send Worker is a separate
101
110
  * deploy with no request and no config, so anything it does not bundle is stamped into it as a
102
111
  * variable — and the kit's own translations were doing that on every provision run. Held here,
103
112
  * they are built into the host and only an adopter's diff travels.
@@ -122,6 +131,7 @@ function email(config) {
122
131
  */
123
132
  compose: ({ capabilities }) => {
124
133
  meter = composedUsageMeter(capabilities);
134
+ composition = capabilities;
125
135
  for (const composed of capabilities) {
126
136
  if (composed.name !== "i18n") continue;
127
137
  const candidate = composed.layersFor;
@@ -160,6 +170,16 @@ function email(config) {
160
170
  retained: emailSuppressionsRetainedTables
161
171
  }
162
172
  },
173
+ purge: [emailUserPurge()],
174
+ processing: EMAIL_PROCESSING,
175
+ /**
176
+ * What email processes under consent: marketing mail and open and click tracking. With
177
+ * `@pithy-sh/consent` composed, an enqueue asks before either; without it, nothing is gated and `pithy doctor`
178
+ * says tracking runs with no consent record behind it.
179
+ */
180
+ consentPurposes: EMAIL_CONSENT_PURPOSES,
181
+ consentWithdrawn: emailConsentWithdrawn,
182
+ consentGranted: emailConsentGranted,
163
183
  /**
164
184
  * The two durable jobs email owns. Both classes live in the prebuilt email worker
165
185
  * (`workflows/worker.ts`), never in the app worker — the app only ever dispatches into `send`.
@@ -204,7 +224,7 @@ function email(config) {
204
224
  */
205
225
  adminRoutes: emailAdminRoutes(resolved.basePath),
206
226
  /**
207
- * How `pithy doctor` checks that these settings **work**, not merely that they are written (#411).
227
+ * How `pithy doctor` checks that these settings **work**, not merely that they are written.
208
228
  *
209
229
  * Built from the resolved config, on the instance, so discovery needs no `pithy.manifest.json` and no
210
230
  * import of this package by the CLI. The local half runs `workflows/hostEnv.ts` — the very declaration
@@ -253,6 +273,7 @@ function email(config) {
253
273
  sender: emailSenderBinding(env),
254
274
  suppressionDb: env.EMAIL_SUPPRESSIONS ? emailSuppressionDatabase(env.EMAIL_SUPPRESSIONS) : void 0,
255
275
  meter: chargeFor(env),
276
+ consent: composedConsent(composition, env),
256
277
  now: /* @__PURE__ */ new Date(),
257
278
  newId: () => crypto.randomUUID()
258
279
  }, input);
@@ -0,0 +1,57 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { ConsentPurpose } from "@pithy-sh/core/src/consent/purpose";
4
+ import type { ConsentGrant, ConsentReader, ConsentSubject, ConsentWithdrawal } from "@pithy-sh/core/src/consent/reader";
5
+ /**
6
+ * Email under consent.
7
+ *
8
+ * Email does two things a law may require consent for: it tracks opens and clicks, and it sends marketing mail. It
9
+ * declares each as a purpose, and when `@pithy-sh/consent` is composed it asks before doing either. Transactional
10
+ * mail is never gated: a sign-in link answers something the person just did. Without consent composed, email
11
+ * gates nothing, and `pithy doctor` names that tracking runs with no consent record behind it.
12
+ */
13
+ /** Marketing mail: a template whose category is `marketing`. */
14
+ export declare const EMAIL_MARKETING_PURPOSE = "email.marketing";
15
+ /** Open and click tracking, on any template that would track. */
16
+ export declare const EMAIL_TRACKING_PURPOSE = "email.tracking";
17
+ /** The purposes email declares. Version 1 of each; a change to what they allow is a version bump here. */
18
+ export declare const EMAIL_CONSENT_PURPOSES: readonly ConsentPurpose[];
19
+ /** What the consent gate decided for one enqueue. */
20
+ export interface ConsentGate {
21
+ /** The purpose that withholds the message, or `null` when it may be sent. */
22
+ readonly withheld: string | null;
23
+ /** Whether open and click tracking may run. */
24
+ readonly tracking: boolean;
25
+ }
26
+ /**
27
+ * Decide, for one message, what consent allows. With no reader, nothing is gated. With one, a marketing message
28
+ * needs the subject's consent to `email.marketing` and tracking needs `email.tracking`; a message with no subject
29
+ * has nobody whose consent could be shown, so it is withheld if marketing and untracked either way. Transactional
30
+ * mail is never withheld.
31
+ */
32
+ export declare function consentGate(reader: ConsentReader | null | undefined, subject: ConsentSubject | undefined, marketing: boolean): Promise<ConsentGate>;
33
+ /**
34
+ * Keep email in step with a withdrawal.
35
+ *
36
+ * - **`email.marketing`**: the address is suppressed for marketing — an `unsubscribe`, which blocks elective mail
37
+ * and never a sign-in link — so the suppression list and the consent record never disagree. The suppression it
38
+ * leaves is permanent, because it is what holds a message already scheduled. An address already suppressed for
39
+ * good keeps its row: a hard bounce is stronger than an unsubscribe and is never downgraded. A time-boxed row is
40
+ * not left to expire under the withdrawal: a lapsed one, or a live time-boxed unsubscribe, is replaced by the
41
+ * withdrawal's own; a live time-boxed bounce, complaint or manual keeps its reason and becomes permanent.
42
+ * - **`email.tracking`**: mail already queued to the address stops tracking. It was decided at enqueue, and the
43
+ * person has since said no.
44
+ *
45
+ * A visitor has no address to act on; their next enqueue is gated by the record instead.
46
+ */
47
+ export declare function emailConsentWithdrawn(withdrawal: ConsentWithdrawal): Promise<void>;
48
+ /**
49
+ * Keep email in step with a grant: the other half of {@link emailConsentWithdrawn}.
50
+ *
51
+ * Granting `email.marketing` again lifts the suppression a withdrawal wrote — an `unsubscribe` whose detail is the
52
+ * withdrawal's own sentence — so the person's yes is heard. Nothing else is ever lifted: a bounce, a complaint, an
53
+ * unsubscribe from a mail's own link, and an operator's manual suppression all stand, because none of them was the
54
+ * consent record's to begin with.
55
+ */
56
+ export declare function emailConsentGranted(grant: ConsentGrant): Promise<void>;
57
+ //# sourceMappingURL=consent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/consent/consent.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAIxH;;;;;;;GAOG;AAEH,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAEzD,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,0GAA0G;AAC1G,eAAO,MAAM,sBAAsB,EAAE,SAAS,cAAc,EAmB3D,CAAC;AAEF,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAKD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACxC,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,WAAW,CAAC,CAKtB;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8DxF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5E"}
@@ -0,0 +1,135 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { emailDatabase, emailSuppressionDatabase } from "../data/tables.js";
4
+ import { normalizeAddress } from "@pithy-sh/core/src/address/address";
5
+ import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
6
+ //#region src/consent/consent.ts
7
+ /**
8
+ * Email under consent.
9
+ *
10
+ * Email does two things a law may require consent for: it tracks opens and clicks, and it sends marketing mail. It
11
+ * declares each as a purpose, and when `@pithy-sh/consent` is composed it asks before doing either. Transactional
12
+ * mail is never gated: a sign-in link answers something the person just did. Without consent composed, email
13
+ * gates nothing, and `pithy doctor` names that tracking runs with no consent record behind it.
14
+ */
15
+ /** Marketing mail: a template whose category is `marketing`. */
16
+ const EMAIL_MARKETING_PURPOSE = "email.marketing";
17
+ /** Open and click tracking, on any template that would track. */
18
+ const EMAIL_TRACKING_PURPOSE = "email.tracking";
19
+ /** The purposes email declares. Version 1 of each; a change to what they allow is a version bump here. */
20
+ const EMAIL_CONSENT_PURPOSES = [{
21
+ id: EMAIL_MARKETING_PURPOSE,
22
+ summary: "Send me news and offers by email.",
23
+ noticeVersion: 1,
24
+ classes: ["pii"],
25
+ explicit: false,
26
+ minimumMethod: "click",
27
+ writtenWithdrawal: false
28
+ }, {
29
+ id: EMAIL_TRACKING_PURPOSE,
30
+ summary: "Tell the sender when I open their email or follow a link in it.",
31
+ noticeVersion: 1,
32
+ classes: ["pii"],
33
+ explicit: false,
34
+ minimumMethod: "click",
35
+ writtenWithdrawal: false
36
+ }];
37
+ /** Ungated: no consent capability is composed, so nothing is withheld and tracking is left to the template. */
38
+ const UNGATED = {
39
+ withheld: null,
40
+ tracking: true
41
+ };
42
+ /**
43
+ * Decide, for one message, what consent allows. With no reader, nothing is gated. With one, a marketing message
44
+ * needs the subject's consent to `email.marketing` and tracking needs `email.tracking`; a message with no subject
45
+ * has nobody whose consent could be shown, so it is withheld if marketing and untracked either way. Transactional
46
+ * mail is never withheld.
47
+ */
48
+ async function consentGate(reader, subject, marketing) {
49
+ if (!reader) return UNGATED;
50
+ const holds = async (purpose) => subject !== void 0 && await reader.hasConsent(subject, purpose);
51
+ return {
52
+ withheld: marketing && !await holds("email.marketing") ? EMAIL_MARKETING_PURPOSE : null,
53
+ tracking: await holds(EMAIL_TRACKING_PURPOSE)
54
+ };
55
+ }
56
+ /** The detail a withdrawal's suppression carries — and the only suppression a later grant lifts. */
57
+ const WITHDRAWAL_DETAIL = `consent withdrawn: ${EMAIL_MARKETING_PURPOSE}`;
58
+ /** The bindings the listener writes through. */
59
+ function bindingOf(env, name) {
60
+ const binding = env[name];
61
+ return typeof binding === "object" && binding !== null ? binding : void 0;
62
+ }
63
+ /**
64
+ * Keep email in step with a withdrawal.
65
+ *
66
+ * - **`email.marketing`**: the address is suppressed for marketing — an `unsubscribe`, which blocks elective mail
67
+ * and never a sign-in link — so the suppression list and the consent record never disagree. The suppression it
68
+ * leaves is permanent, because it is what holds a message already scheduled. An address already suppressed for
69
+ * good keeps its row: a hard bounce is stronger than an unsubscribe and is never downgraded. A time-boxed row is
70
+ * not left to expire under the withdrawal: a lapsed one, or a live time-boxed unsubscribe, is replaced by the
71
+ * withdrawal's own; a live time-boxed bounce, complaint or manual keeps its reason and becomes permanent.
72
+ * - **`email.tracking`**: mail already queued to the address stops tracking. It was decided at enqueue, and the
73
+ * person has since said no.
74
+ *
75
+ * A visitor has no address to act on; their next enqueue is gated by the record instead.
76
+ */
77
+ async function emailConsentWithdrawn(withdrawal) {
78
+ const address = await withdrawal.address();
79
+ if (address === null) return;
80
+ const now = /* @__PURE__ */ new Date();
81
+ if (withdrawal.purpose === "email.marketing") {
82
+ const suppressions = bindingOf(withdrawal.env, "EMAIL_SUPPRESSIONS");
83
+ if (!suppressions) return;
84
+ await emailSuppressionDatabase(suppressions).insertInto("pithyEmailSuppressions").values({
85
+ email: normalizeAddress(address),
86
+ reason: "unsubscribe",
87
+ jobId: null,
88
+ environment: null,
89
+ detail: WITHDRAWAL_DETAIL,
90
+ expiresAt: null,
91
+ createdAt: SQLiteDate.encode(now)
92
+ }).onConflict((conflict) => conflict.column("email").doUpdateSet((eb) => {
93
+ const takes = eb.or([eb("pithyEmailSuppressions.expiresAt", "<=", SQLiteDate.encode(now)), eb("pithyEmailSuppressions.reason", "=", "unsubscribe")]);
94
+ return {
95
+ reason: eb.case().when(takes).then("unsubscribe").else(eb.ref("pithyEmailSuppressions.reason")).end(),
96
+ detail: eb.case().when(takes).then(WITHDRAWAL_DETAIL).else(eb.ref("pithyEmailSuppressions.detail")).end(),
97
+ jobId: eb.case().when(takes).then(null).else(eb.ref("pithyEmailSuppressions.jobId")).end(),
98
+ environment: eb.case().when(takes).then(null).else(eb.ref("pithyEmailSuppressions.environment")).end(),
99
+ expiresAt: null
100
+ };
101
+ }).where("pithyEmailSuppressions.expiresAt", "is not", null)).execute();
102
+ return;
103
+ }
104
+ if (withdrawal.purpose === "email.tracking") {
105
+ const db = bindingOf(withdrawal.env, "DB");
106
+ if (!db) return;
107
+ await emailDatabase(db).updateTable("pithyEmailJobs").set({
108
+ openTracking: SQLiteBoolean.encode(false),
109
+ clickTracking: SQLiteBoolean.encode(false),
110
+ updatedAt: SQLiteDate.encode(now)
111
+ }).where("recipientKey", "=", normalizeAddress(address)).where("status", "in", [
112
+ "pending",
113
+ "scheduled",
114
+ "undispatched"
115
+ ]).execute();
116
+ }
117
+ }
118
+ /**
119
+ * Keep email in step with a grant: the other half of {@link emailConsentWithdrawn}.
120
+ *
121
+ * Granting `email.marketing` again lifts the suppression a withdrawal wrote — an `unsubscribe` whose detail is the
122
+ * withdrawal's own sentence — so the person's yes is heard. Nothing else is ever lifted: a bounce, a complaint, an
123
+ * unsubscribe from a mail's own link, and an operator's manual suppression all stand, because none of them was the
124
+ * consent record's to begin with.
125
+ */
126
+ async function emailConsentGranted(grant) {
127
+ if (grant.purpose !== "email.marketing") return;
128
+ const address = await grant.address();
129
+ if (address === null) return;
130
+ const suppressions = bindingOf(grant.env, "EMAIL_SUPPRESSIONS");
131
+ if (!suppressions) return;
132
+ await emailSuppressionDatabase(suppressions).deleteFrom("pithyEmailSuppressions").where("email", "=", normalizeAddress(address)).where("reason", "=", "unsubscribe").where("detail", "=", WITHDRAWAL_DETAIL).execute();
133
+ }
134
+ //#endregion
135
+ export { EMAIL_CONSENT_PURPOSES, EMAIL_MARKETING_PURPOSE, EMAIL_TRACKING_PURPOSE, consentGate, emailConsentGranted, emailConsentWithdrawn };
@@ -9,7 +9,7 @@ import { z } from "zod";
9
9
  export declare const EmailEvent: z.ZodObject<{
10
10
  id: z.ZodNumber;
11
11
  jobId: z.ZodString;
12
- recipient: z.ZodString;
12
+ recipient: import("@pithy-sh/core/src/privacy/classes").Marked<z.ZodString, "pii">;
13
13
  type: z.ZodEnum<{
14
14
  bounce: "bounce";
15
15
  click: "click";
@@ -1 +1 @@
1
- {"version":3,"file":"emailEvent.d.ts","sourceRoot":"","sources":["../../src/data/emailEvent.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;iBA4B8C,CAAC;AACtE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC"}
1
+ {"version":3,"file":"emailEvent.d.ts","sourceRoot":"","sources":["../../src/data/emailEvent.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;iBA4B8C,CAAC;AACtE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC"}
@@ -3,6 +3,7 @@
3
3
  import { EmailEventType } from "./enums.js";
4
4
  import { z } from "zod";
5
5
  import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
6
+ import { pii } from "@pithy-sh/core/src/privacy/classes";
6
7
  //#region src/data/emailEvent.ts
7
8
  /**
8
9
  * One row in `pithy_email_events` — a per-recipient event for history and campaign attribution. The
@@ -12,7 +13,7 @@ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
12
13
  const EmailEvent = z.object({
13
14
  id: z.number().int().describe("Surrogate primary key, autoincremented by SQLite."),
14
15
  jobId: z.string().describe("The `pithy_email_jobs.id` this event belongs to."),
15
- recipient: z.string().describe("The recipient address the event is about."),
16
+ recipient: pii(z.string().describe("The recipient address the event is about.")),
16
17
  type: EmailEventType.describe("What happened: sent, open, click, bounce, complaint, unsubscribe, suppressed, or failed."),
17
18
  linkLabel: z.string().nullish().describe("For a `click` event, the link's identity/label as declared at render; null otherwise."),
18
19
  linkUrl: z.string().nullish().describe("For a `click` event, the destination URL that was followed; null otherwise."),
@@ -25,8 +25,8 @@ export declare const SPENT_PAYLOAD: string | Record<string, unknown>;
25
25
  */
26
26
  export declare const EmailJob: z.ZodObject<{
27
27
  id: z.ZodString;
28
- toAddress: z.ZodString;
29
- recipientKey: z.ZodString;
28
+ toAddress: import("@pithy-sh/core/src/privacy/classes").Marked<z.ZodString, "pii">;
29
+ recipientKey: import("@pithy-sh/core/src/privacy/classes").Marked<z.ZodString, "pii">;
30
30
  fromAddress: z.ZodString;
31
31
  fromName: z.ZodString;
32
32
  subject: z.ZodString;
@@ -75,4 +75,8 @@ export declare const EmailJob: z.ZodObject<{
75
75
  sentAt: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
76
76
  }, z.core.$strip>;
77
77
  export type EmailJob = z.output<typeof EmailJob>;
78
+ /** A person's email address as the email tables hold it: marked `pii`, so it never compiles into a log field. */
79
+ export type PersonalAddress = EmailJob["toAddress"];
80
+ /** Mark an address the caller handed in as the personal data it is, for a row that stores it. */
81
+ export declare function personalAddress(value: string): PersonalAddress;
78
82
  //# sourceMappingURL=emailJob.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"emailJob.d.ts","sourceRoot":"","sources":["../../src/data/emailJob.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AACH,eAAO,MAAM,eAAe,wCAIzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,kCAAyC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoGkF,CAAC;AACxG,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC"}
1
+ {"version":3,"file":"emailJob.d.ts","sourceRoot":"","sources":["../../src/data/emailJob.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AACH,eAAO,MAAM,eAAe,wCAIzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,kCAAyC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwGkF,CAAC;AACxG,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD,iHAAiH;AACjH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;AAEpD,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAE9D"}
@@ -3,6 +3,7 @@
3
3
  import { EmailJobStatus, SendMode, TemplateCategory } from "./enums.js";
4
4
  import { z } from "zod";
5
5
  import { SQLiteBoolean, SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
6
+ import { pii } from "@pithy-sh/core/src/privacy/classes";
6
7
  import { Locale } from "@pithy-sh/core/src/i18n/locale";
7
8
  //#region src/data/emailJob.ts
8
9
  /**
@@ -28,8 +29,8 @@ const SPENT_PAYLOAD = sqliteJson(EmailJobPayload).encode({});
28
29
  */
29
30
  const EmailJob = z.object({
30
31
  id: z.string().describe("UUID primary key. Text, not autoincrement, so a job id embedded in a tracking link cannot be enumerated."),
31
- toAddress: z.string().describe("The recipient's email address. Lowercased and checked against the suppression list before sending."),
32
- recipientKey: z.string().describe("The recipient under `normalizeAddress` — the one form every comparison in the kit is against, and the only column anything matches a recipient on. `toAddress` deliberately keeps what the caller typed, because an operator diagnosing a send needs to see the string that was actually addressed; that makes it useless as a key, since `Ada@example.com` and `ada@example.com` are one mailbox and two rows. Doing the folding in SQL instead would not work: SQLite's `lower()` is ASCII-only while `normalizeAddress` is `toLowerCase()`, so the two disagree on exactly the addresses nobody tests with. The same value `pithy_email_events.recipient` is keyed on, so a job and its events agree on who the person is."),
32
+ toAddress: pii(z.string().describe("The recipient's email address. Lowercased and checked against the suppression list before sending.")),
33
+ recipientKey: pii(z.string().describe("The recipient under `normalizeAddress` — the one form every comparison in the kit is against, and the only column anything matches a recipient on. `toAddress` deliberately keeps what the caller typed, because an operator diagnosing a send needs to see the string that was actually addressed; that makes it useless as a key, since `Ada@example.com` and `ada@example.com` are one mailbox and two rows. Doing the folding in SQL instead would not work: SQLite's `lower()` is ASCII-only while `normalizeAddress` is `toLowerCase()`, so the two disagree on exactly the addresses nobody tests with. The same value `pithy_email_events.recipient` is keyed on, so a job and its events agree on who the person is.")),
33
34
  fromAddress: z.string().describe("The sender address. Must use a domain onboarded onto Cloudflare Email Service."),
34
35
  fromName: z.string().describe("The sender display name recipients see in their inbox."),
35
36
  subject: z.string().describe("The rendered subject line."),
@@ -60,5 +61,9 @@ const EmailJob = z.object({
60
61
  updatedAt: SQLiteDate.describe("When the job row was last written."),
61
62
  sentAt: SQLiteDate.nullish().describe("When the send succeeded; null until then.")
62
63
  }).describe("One email job in `pithy_email_jobs` — the auditable, retryable record of a single email.");
64
+ /** Mark an address the caller handed in as the personal data it is, for a row that stores it. */
65
+ function personalAddress(value) {
66
+ return value;
67
+ }
63
68
  //#endregion
64
- export { EmailJob, EmailJobPayload, SPENT_PAYLOAD };
69
+ export { EmailJob, EmailJobPayload, SPENT_PAYLOAD, personalAddress };
@@ -8,7 +8,7 @@ import { z } from "zod";
8
8
  */
9
9
  export declare const EmailSuppression: z.ZodObject<{
10
10
  id: z.ZodNumber;
11
- email: z.ZodString;
11
+ email: import("@pithy-sh/core/src/privacy/classes").Marked<z.ZodString, "pii">;
12
12
  reason: z.ZodEnum<{
13
13
  complaint: "complaint";
14
14
  hard_bounce: "hard_bounce";
@@ -1 +1 @@
1
- {"version":3,"file":"emailSuppression.d.ts","sourceRoot":"","sources":["../../src/data/emailSuppression.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBA0BuC,CAAC;AACrE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
1
+ {"version":3,"file":"emailSuppression.d.ts","sourceRoot":"","sources":["../../src/data/emailSuppression.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBA0BuC,CAAC;AACrE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
@@ -3,6 +3,7 @@
3
3
  import { SuppressionReason } from "./enums.js";
4
4
  import { z } from "zod";
5
5
  import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
6
+ import { pii } from "@pithy-sh/core/src/privacy/classes";
6
7
  //#region src/data/emailSuppression.ts
7
8
  /**
8
9
  * One row in `pithy_email_suppressions` — an address that must not be sent to, fed by hard bounces,
@@ -11,7 +12,7 @@ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
11
12
  */
12
13
  const EmailSuppression = z.object({
13
14
  id: z.number().int().describe("Surrogate primary key, autoincremented by SQLite."),
14
- email: z.string().describe("The suppressed address, lowercased. Uniquely indexed — one row per address."),
15
+ email: pii(z.string().describe("The suppressed address, lowercased. Uniquely indexed — one row per address.")),
15
16
  reason: SuppressionReason.describe("Why the address is suppressed: hard bounce, complaint, unsubscribe, or manual."),
16
17
  jobId: z.string().nullish().describe("The job that triggered the suppression (a bounce/complaint/unsubscribe), if any. Job ids are per-environment, so pair it with `environment` for context."),
17
18
  environment: z.string().nullish().describe("The environment the triggering job came from (e.g. `prod`, `feature-27`). The suppression itself is global; this records where it originated."),
@@ -15,8 +15,8 @@ import type { Kysely } from "kysely";
15
15
  export declare const emailTables: {
16
16
  pithyEmailJobs: import("zod").ZodObject<{
17
17
  id: import("zod").ZodString;
18
- toAddress: import("zod").ZodString;
19
- recipientKey: import("zod").ZodString;
18
+ toAddress: import("@pithy-sh/core/src/privacy/classes").Marked<import("zod").ZodString, "pii">;
19
+ recipientKey: import("@pithy-sh/core/src/privacy/classes").Marked<import("zod").ZodString, "pii">;
20
20
  fromAddress: import("zod").ZodString;
21
21
  fromName: import("zod").ZodString;
22
22
  subject: import("zod").ZodString;
@@ -67,7 +67,7 @@ export declare const emailTables: {
67
67
  pithyEmailEvents: import("zod").ZodObject<{
68
68
  id: import("zod").ZodNumber;
69
69
  jobId: import("zod").ZodString;
70
- recipient: import("zod").ZodString;
70
+ recipient: import("@pithy-sh/core/src/privacy/classes").Marked<import("zod").ZodString, "pii">;
71
71
  type: import("zod").ZodEnum<{
72
72
  bounce: "bounce";
73
73
  click: "click";
@@ -90,7 +90,7 @@ export type EmailTables = typeof emailTables;
90
90
  export declare const emailSuppressionTables: {
91
91
  pithyEmailSuppressions: import("zod").ZodObject<{
92
92
  id: import("zod").ZodNumber;
93
- email: import("zod").ZodString;
93
+ email: import("@pithy-sh/core/src/privacy/classes").Marked<import("zod").ZodString, "pii">;
94
94
  reason: import("zod").ZodEnum<{
95
95
  complaint: "complaint";
96
96
  hard_bounce: "hard_bounce";
@@ -1,6 +1,6 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
3
+ import type { AdminRouteDeclaration } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
4
4
  import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
5
5
  /**
6
6
  * Email's control-plane scopes, and the admin surface a manifest advertises.
@@ -97,5 +97,5 @@ export declare const EMAIL_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
97
97
  * The summaries say what the operation is *for*. A client renders these next to a button somebody is
98
98
  * about to press on a real person's mail.
99
99
  */
100
- export declare function emailAdminRoutes(basePath: string): AdminRoute[];
100
+ export declare function emailAdminRoutes(basePath: string): AdminRouteDeclaration[];
101
101
  //# sourceMappingURL=guards.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAsC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F,kGAAkG;AAClG,eAAO,MAAM,8BAA8B,EAAE,iBAA8C,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,iBAA+C,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EAMlE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAuC/D"}
1
+ {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAsC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F,kGAAkG;AAClG,eAAO,MAAM,8BAA8B,EAAE,iBAA8C,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,iBAA+C,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EAMlE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAmD1E"}
@@ -106,38 +106,50 @@ function emailAdminRoutes(basePath) {
106
106
  return [
107
107
  {
108
108
  method: "GET",
109
+ operation: "jobs.list",
109
110
  path: `${basePath}/jobs`,
110
111
  scope: EMAIL_JOBS_READ_SCOPE,
112
+ kind: "reads",
111
113
  summary: "The send log, newest first, filtered by status. Recipients are masked in the list."
112
114
  },
113
115
  {
114
116
  method: "GET",
117
+ operation: "jobs.read",
115
118
  path: `${basePath}/jobs/:id`,
116
119
  scope: EMAIL_JOBS_READ_SCOPE,
120
+ kind: "reads",
117
121
  summary: "One job in full — the recipient, the subject, and why it failed. Never the template variables."
118
122
  },
119
123
  {
120
124
  method: "POST",
125
+ operation: "jobs.retry",
121
126
  path: `${basePath}/jobs/:id/retry`,
122
127
  scope: EMAIL_JOBS_RETRY_SCOPE,
128
+ kind: "sends",
123
129
  summary: "Queue a failed job again with a fresh attempt budget. Sends real mail."
124
130
  },
125
131
  {
126
132
  method: "GET",
133
+ operation: "suppressions.list",
127
134
  path: `${basePath}/suppressions`,
128
135
  scope: EMAIL_SUPPRESSIONS_READ_SCOPE,
136
+ kind: "reads",
129
137
  summary: "Addresses this project will not send to, and why. Global — every environment shares it."
130
138
  },
131
139
  {
132
140
  method: "POST",
141
+ operation: "suppressions.add",
133
142
  path: `${basePath}/suppressions`,
134
143
  scope: EMAIL_SUPPRESSIONS_WRITE_SCOPE,
144
+ kind: "writes",
135
145
  summary: "Block an address by hand, permanently or until a date. Recorded as a manual block."
136
146
  },
137
147
  {
138
148
  method: "POST",
149
+ operation: "suppressions.remove",
139
150
  path: `${basePath}/suppressions/remove`,
140
151
  scope: EMAIL_SUPPRESSIONS_DELETE_SCOPE,
152
+ kind: "deletes",
141
153
  summary: "Unblock an address. Re-opens sending to somebody who bounced, complained, or opted out."
142
154
  }
143
155
  ];
@@ -0,0 +1,9 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { ProcessingActivityInput } from "@pithy-sh/core/src/processing/activity";
4
+ /**
5
+ * What email does with personal data: it sends the mail the Worker enqueues, and, under each purpose's consent,
6
+ * marketing mail and open and click tracking.
7
+ */
8
+ export declare const EMAIL_PROCESSING: readonly ProcessingActivityInput[];
9
+ //# sourceMappingURL=activities.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"activities.d.ts","sourceRoot":"","sources":["../../src/processing/activities.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAA4B,MAAM,wCAAwC,CAAC;AAUhH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,uBAAuB,EAuB9D,CAAC"}
@@ -0,0 +1,40 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { EMAIL_MARKETING_PURPOSE, EMAIL_TRACKING_PURPOSE } from "../consent/consent.js";
4
+ //#region src/processing/activities.ts
5
+ /** The mail provider every send goes through. */
6
+ const EMAIL_SERVICE = {
7
+ name: "Cloudflare Email Service",
8
+ receives: "Each recipient's address and the message sent to it.",
9
+ classes: ["pii"]
10
+ };
11
+ /**
12
+ * What email does with personal data: it sends the mail the Worker enqueues, and, under each purpose's consent,
13
+ * marketing mail and open and click tracking.
14
+ */
15
+ const EMAIL_PROCESSING = [
16
+ {
17
+ id: "email.delivery",
18
+ purpose: "Send the mail a person's account needs — sign-in links, codes, notices — and keep its history.",
19
+ classes: ["pii"],
20
+ legalBasis: "contract",
21
+ recipients: [EMAIL_SERVICE]
22
+ },
23
+ {
24
+ id: "email.marketing",
25
+ purpose: "Send news and offers by email to a person who agreed to receive them.",
26
+ classes: ["pii"],
27
+ legalBasis: "consent",
28
+ consentPurpose: EMAIL_MARKETING_PURPOSE,
29
+ recipients: [EMAIL_SERVICE]
30
+ },
31
+ {
32
+ id: "email.tracking",
33
+ purpose: "Record when a person opens a message or follows a link in it, for a person who agreed to it.",
34
+ classes: ["pii"],
35
+ legalBasis: "consent",
36
+ consentPurpose: EMAIL_TRACKING_PURPOSE
37
+ }
38
+ ];
39
+ //#endregion
40
+ export { EMAIL_PROCESSING };