@pithy-sh/email 0.7.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.js +7 -10
- 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.ts +10 -13
- 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.
|
package/dist/capability.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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 —
|
package/dist/capability.d.ts.map
CHANGED
|
@@ -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;
|
|
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"}
|
package/dist/capability.js
CHANGED
|
@@ -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
|
|
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
|
|
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":"
|
|
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"}
|
package/dist/data/emailEvent.js
CHANGED
|
@@ -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."),
|
package/dist/data/emailJob.d.ts
CHANGED
|
@@ -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":"
|
|
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"}
|
package/dist/data/emailJob.js
CHANGED
|
@@ -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":"
|
|
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."),
|
package/dist/data/tables.d.ts
CHANGED
|
@@ -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";
|
package/dist/http/guards.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import type {
|
|
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):
|
|
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,
|
|
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"}
|
package/dist/http/guards.js
CHANGED
|
@@ -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 };
|