@pithy-sh/email 0.9.0 → 0.10.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.
@@ -41,7 +41,14 @@ import {
41
41
  EmailSuppressResponse,
42
42
  EmailUnsuppressResponse,
43
43
  } from "./responses";
44
- import { JobIdParam, JobsQuery, SuppressionsQuery, SuppressRequest, UnsuppressRequest } from "./schemas";
44
+ import {
45
+ JobIdParam,
46
+ JobsQuery,
47
+ SuppressionLookupRequest,
48
+ SuppressionsQuery,
49
+ SuppressRequest,
50
+ UnsuppressRequest,
51
+ } from "./schemas";
45
52
  import { jobDetailView, jobListView, suppressionView } from "./view";
46
53
 
47
54
  /**
@@ -51,6 +58,7 @@ import { jobDetailView, jobListView, suppressionView } from "./view";
51
58
  * GET /email/jobs/:id → one job in full (control-plane: email:jobs:read) param
52
59
  * POST /email/jobs/:id/retry → queue it again (control-plane: email:jobs:retry) param
53
60
  * GET /email/suppressions → who we won't mail (control-plane: email:suppressions:read) query
61
+ * POST /email/suppressions/lookup → is this one blocked (control-plane: email:suppressions:read) json
54
62
  * POST /email/suppressions → block an address (control-plane: email:suppressions:write) json
55
63
  * POST /email/suppressions/remove → unblock one (control-plane: email:suppressions:delete) json
56
64
  *
@@ -71,10 +79,13 @@ import { jobDetailView, jobListView, suppressionView } from "./view";
71
79
  * parsing every response would spend a validation pass on rows this Worker just read, and would turn a
72
80
  * shape mistake into a 500 in production rather than a red build.
73
81
  *
74
- * **Removal is a POST with a body, not `DELETE /suppressions/:email`.** An address in a path is an
75
- * address in every access log, every proxy, every trace, and every referrer between the client and the
76
- * Worker. The record is personal data whether or not it is a person's current address, so it travels in
77
- * a body. Testers' `POST /remove` is the same call made for the same reason.
82
+ * **An address never travels in a URL.** Removal is `POST /suppressions/remove`, not
83
+ * `DELETE /suppressions/:email`, and a lookup is `POST /suppressions/lookup`, not `?email=`. A path or a
84
+ * query string is in every access log, every proxy, every trace, and every referrer between the client
85
+ * and the Worker. The record is personal data whether or not it is a person's current address, so it
86
+ * travels in a body. Testers' `POST /remove` is the same call made for the same reason, and
87
+ * `addressedParameters` in `@pithy-sh/core/src/openapi/document` fails the kit's build on a route that
88
+ * declares one in its URL.
78
89
  */
79
90
 
80
91
  /** What every route this capability mounts declares: its path, its strategy, and the scope it checks. */
@@ -100,6 +111,12 @@ export const EMAIL_ADMIN_ROUTES: readonly EmailRouteDeclaration[] = [
100
111
  { method: "GET", path: "/jobs/:id", strategy: "control-plane", scope: EMAIL_JOBS_READ_SCOPE },
101
112
  { method: "POST", path: "/jobs/:id/retry", strategy: "control-plane", scope: EMAIL_JOBS_RETRY_SCOPE },
102
113
  { method: "GET", path: "/suppressions", strategy: "control-plane", scope: EMAIL_SUPPRESSIONS_READ_SCOPE },
114
+ {
115
+ method: "POST",
116
+ path: "/suppressions/lookup",
117
+ strategy: "control-plane",
118
+ scope: EMAIL_SUPPRESSIONS_READ_SCOPE,
119
+ },
103
120
  { method: "POST", path: "/suppressions", strategy: "control-plane", scope: EMAIL_SUPPRESSIONS_WRITE_SCOPE },
104
121
  {
105
122
  method: "POST",
@@ -182,6 +199,33 @@ function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
182
199
  return context;
183
200
  }
184
201
 
202
+ /** What one read of the suppression list records about itself. The rows never go in. */
203
+ interface SuppressionsReadMetadata {
204
+ reason: string | null;
205
+ lookup: boolean;
206
+ active: boolean | null;
207
+ returned: number;
208
+ paged: boolean;
209
+ }
210
+
211
+ /**
212
+ * Audit a read of the suppression list. The heaviest read in the capability: this database is global, so
213
+ * a page of it is a page of every environment's bounces, complaints, and opt-outs. Audited with whether
214
+ * it was a lookup or a walk, because those are very different events.
215
+ */
216
+ async function auditSuppressionsRead(c: Context<PithyHonoEnv>, metadata: SuppressionsReadMetadata): Promise<void> {
217
+ const who = caller(c);
218
+ await c.var.emit({
219
+ action: EmailAuditActions.suppressionsRead,
220
+ outcome: "success",
221
+ actorType: "control-plane",
222
+ actorId: who.subject,
223
+ resourceType: "email_suppression",
224
+ resourceId: null,
225
+ metadata: { connectionId: who.connectionId, ...metadata },
226
+ });
227
+ }
228
+
185
229
  /** Register the email management sub-router. Composed alongside the public callbacks. */
186
230
  export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
187
231
  const base = options.basePath;
@@ -320,7 +364,7 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
320
364
  app.get(
321
365
  `${base}/suppressions`,
322
366
  describeRoute({
323
- summary: "Page through the suppression list, or look one address up.",
367
+ summary: "Page through the suppression list.",
324
368
  verification: "control-plane",
325
369
  scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
326
370
  responses: { 200: EmailSuppressionsResponse },
@@ -329,28 +373,49 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
329
373
  validate("query", SuppressionsQuery),
330
374
  async (c) => {
331
375
  const query = c.req.valid("query");
332
- const who = caller(c);
333
376
  const now = clock();
334
377
  const page = await listSuppressions(suppressions(c), { ...query, now });
335
378
 
336
- // The heaviest read in the capability: this database is global, so a page of it is a page of
337
- // every environment's bounces, complaints, and opt-outs. Audited with whether it was a lookup
338
- // or a walk, because those are very different events wearing the same route.
339
- await c.var.emit({
340
- action: EmailAuditActions.suppressionsRead,
341
- outcome: "success",
342
- actorType: "control-plane",
343
- actorId: who.subject,
344
- resourceType: "email_suppression",
345
- resourceId: null,
346
- metadata: {
347
- connectionId: who.connectionId,
348
- reason: query.reason ?? null,
349
- lookup: Boolean(query.email),
350
- active: query.active ?? null,
351
- returned: page.items.length,
352
- paged: Boolean(query.cursor),
353
- },
379
+ await auditSuppressionsRead(c, {
380
+ reason: query.reason ?? null,
381
+ lookup: false,
382
+ active: query.active ?? null,
383
+ returned: page.items.length,
384
+ paged: Boolean(query.cursor),
385
+ });
386
+
387
+ return c.json({
388
+ suppressions: page.items.map((row) => suppressionView(row, now)),
389
+ nextCursor: page.nextCursor,
390
+ } satisfies EmailSuppressionsResponse);
391
+ },
392
+ );
393
+
394
+ app.post(
395
+ `${base}/suppressions/lookup`,
396
+ describeRoute({
397
+ summary: "Look one address up on the suppression list.",
398
+ verification: "control-plane",
399
+ scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
400
+ responses: { 200: EmailSuppressionsResponse },
401
+ }),
402
+ requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE),
403
+ validate("json", SuppressionLookupRequest),
404
+ async (c) => {
405
+ const input = c.req.valid("json");
406
+ const now = clock();
407
+ // `listSuppressions` matches the normalized key exactly, and `email` is unique, so this is the
408
+ // row or none: the listing's envelope, so a client renders it with the schema it already holds.
409
+ const page = await listSuppressions(suppressions(c), { email: input.email, now });
410
+
411
+ // The address stays out of the trail: the event records that one address was asked about and
412
+ // whether it was found, as the listing's lookup always did.
413
+ await auditSuppressionsRead(c, {
414
+ reason: null,
415
+ lookup: true,
416
+ active: null,
417
+ returned: page.items.length,
418
+ paged: false,
354
419
  });
355
420
 
356
421
  return c.json({
@@ -396,17 +461,17 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
396
461
  message: "That expiry has already passed, so it would not block anything.",
397
462
  action:
398
463
  "Give a future instant, or omit `expiresAt` to block permanently. To lift an existing block, use the remove route — it requires `email:suppressions:delete`.",
399
- detail: `refused suppression for ${email} with expiresAt ${expiresAt.toISOString()} at ${now.toISOString()}`,
464
+ detail: `refused suppression with expiresAt ${expiresAt.toISOString()} at ${now.toISOString()}`,
400
465
  });
401
466
  }
402
467
 
403
468
  const current = (await listSuppressions(db, { email, limit: 1 })).items[0];
404
469
  if (current && current.reason !== "manual") {
405
470
  throw new ConflictError({
406
- message: `${email} is already suppressed as a ${current.reason}, which this route may not overwrite.`,
471
+ message: `That address is already suppressed as a ${current.reason}, which this route may not overwrite.`,
407
472
  action:
408
473
  "Lift it with the remove route, which requires `email:suppressions:delete` — undoing a bounce, a complaint, or someone's own opt-out is a separate decision.",
409
- detail: `refused manual suppression over an existing ${current.reason} for ${email}`,
474
+ detail: `refused manual suppression over an existing ${current.reason}`,
410
475
  });
411
476
  }
412
477
 
@@ -22,7 +22,7 @@ import { EmailJobStatus, SuppressionReason, TemplateCategory } from "../data/enu
22
22
 
23
23
  /**
24
24
  * The characters a callback token path segment may contain: the base64url alphabet, plus `.` — the
25
- * token's own `<payload>.<signature>` separator, and the `.png` suffix mail clients append to an
25
+ * token's own segment separator, and the `.png` suffix mail clients append to an
26
26
  * open-pixel URL (which `handleOpen` strips before verifying). Deliberately not a strict base64url
27
27
  * check: that would 400 every tracking pixel.
28
28
  */
@@ -30,7 +30,7 @@ const TOKEN_SEGMENT = /^[A-Za-z0-9._-]+$/;
30
30
 
31
31
  /**
32
32
  * The `:token` path parameter every callback route carries. A shape and size bound only — the ceiling
33
- * is generous enough for a click token whose signed claims embed a long destination URL, so no link we
33
+ * is generous enough for a click token whose sealed claims embed a long destination URL, so no link we
34
34
  * mint can exceed it, while an unbounded segment can no longer reach the verifier.
35
35
  */
36
36
  export const CallbackTokenParam = z
@@ -40,26 +40,40 @@ export const CallbackTokenParam = z
40
40
  .min(1)
41
41
  .max(4096)
42
42
  .regex(TOKEN_SEGMENT)
43
- .describe("The signed callback token from the path, optionally with the open-pixel `.png` suffix."),
43
+ .describe("The sealed callback token from the path, optionally with the open-pixel `.png` suffix."),
44
44
  })
45
45
  .describe("The path parameter carrying a click/open/unsubscribe callback token.");
46
46
  export type CallbackTokenParam = z.output<typeof CallbackTokenParam>;
47
47
 
48
+ /** One form field as a client may send it: a value, or a repeated field's values. Anything else reads as absent. */
49
+ const FormField = z
50
+ .union([z.string(), z.array(z.string())])
51
+ .optional()
52
+ .catch(undefined);
53
+
48
54
  /**
49
- * The optional `?reason=` on the unsubscribe callback — supplied by the app's own preferences flow.
50
- * The bound is a ceiling, not the storage limit: the handler still truncates to 200 characters before
51
- * writing, so every real value keeps behaving exactly as it did and only an absurd one is refused.
55
+ * The form body of an unsubscribe `POST`: what a mail client's one-click unsubscribe sends (RFC 8058 fixes it to
56
+ * `List-Unsubscribe=One-Click`), what the confirmation page's button sends, and what the app's own preferences flow
57
+ * sends with a `reason`.
58
+ *
59
+ * **Nothing in it can refuse the opt-out.** Every field is optional, a repeated field or one of the wrong type reads
60
+ * as absent or as its first value, and an over-long reason is truncated by the handler rather than refused. The
61
+ * token is the only gate; a body is never a reason somebody stays subscribed.
62
+ *
63
+ * The reason travels in the body because it is the recipient's own words, and a query string is written to every
64
+ * request log between the client and the Worker. The route reads no query at all.
52
65
  */
53
- export const UnsubscribeQuery = z
66
+ export const UnsubscribeForm = z
54
67
  .object({
55
- reason: z
56
- .string()
57
- .max(2000)
58
- .optional()
59
- .describe("Why the recipient opted out; truncated to 200 characters before it is stored."),
68
+ "List-Unsubscribe": FormField.describe(
69
+ "`One-Click` from a mail client's RFC 8058 one-click unsubscribe. Accepted and not otherwise read.",
70
+ ),
71
+ reason: FormField.describe(
72
+ "Why the recipient opted out; the first value is kept, truncated to 200 characters before it is stored.",
73
+ ),
60
74
  })
61
- .describe("The optional query parameters accepted by the unsubscribe callback.");
62
- export type UnsubscribeQuery = z.output<typeof UnsubscribeQuery>;
75
+ .describe("The optional form fields an unsubscribe POST accepts.");
76
+ export type UnsubscribeForm = z.output<typeof UnsubscribeForm>;
63
77
 
64
78
  /**
65
79
  * Where the next page starts. Opaque, and a malformed one is a first page rather than a 400 — the
@@ -157,19 +171,16 @@ export type JobsQuery = z.output<typeof JobsQuery>;
157
171
  /**
158
172
  * The suppression list query.
159
173
  *
160
- * `email` is an exact-match lookup rather than a search, and that is the point: answering "is this one
161
- * address blocked" should not require paging a list of every other person who ever unsubscribed. A
162
- * prefix or substring search would turn the endpoint into a way to enumerate the list a page at a time
163
- * while looking like a lookup.
174
+ * **No address, and an unknown key is refused.** A query string is written to every request log between
175
+ * the client and the Worker, so looking one address up is {@link SuppressionLookupRequest}, a `POST`
176
+ * with the address in its body. Strict rather than stripping, so a client still sending `?email=` is
177
+ * told so with a 400 instead of being handed the whole list as though it were the match.
164
178
  */
165
179
  export const SuppressionsQuery = z
166
180
  .object({
167
181
  reason: SuppressionReason.optional().describe(
168
182
  "Filter to one reason — hard bounce, complaint, unsubscribe, manual.",
169
183
  ),
170
- email: AddressFilter.optional().describe(
171
- "Look one address up, exactly. Answers `is this person blocked` without disclosing anybody else.",
172
- ),
173
184
  active: z
174
185
  .enum(["true", "false"])
175
186
  .describe("`true` or `false`.")
@@ -181,7 +192,10 @@ export const SuppressionsQuery = z
181
192
  cursor: Cursor,
182
193
  limit: Limit,
183
194
  })
184
- .describe("The suppression-list query: what to filter by, which address to look up, and where to resume.");
195
+ .strict()
196
+ .describe(
197
+ "The suppression-list query: what to filter by and where to resume. To look one address up, POST it to `/suppressions/lookup`.",
198
+ );
185
199
  export type SuppressionsQuery = z.output<typeof SuppressionsQuery>;
186
200
 
187
201
  /**
@@ -213,6 +227,24 @@ export const SuppressRequest = z
213
227
  .describe("Add one address to the global suppression list, as a manual block.");
214
228
  export type SuppressRequest = z.output<typeof SuppressRequest>;
215
229
 
230
+ /**
231
+ * Look one address up.
232
+ *
233
+ * An exact match rather than a search, and that is the point: answering "is this one address blocked"
234
+ * should not require paging a list of every other person who ever unsubscribed, and a prefix or substring
235
+ * search would enumerate the list a page at a time while looking like a lookup. A body because a query
236
+ * string is written to every request log between the client and the Worker.
237
+ */
238
+ export const SuppressionLookupRequest = z
239
+ .object({
240
+ email: AddressFilter.describe(
241
+ "The address to look up, matched exactly against the stored key. Answers `is this person blocked` without disclosing anybody else.",
242
+ ),
243
+ })
244
+ .strict()
245
+ .describe("Look one address up on the global suppression list.");
246
+ export type SuppressionLookupRequest = z.output<typeof SuppressionLookupRequest>;
247
+
216
248
  /** Unblock an address — the undo of {@link SuppressRequest}, and of a bounce, complaint, or opt-out. */
217
249
  export const UnsuppressRequest = z
218
250
  .object({
@@ -19,7 +19,7 @@ import { type EmailTheme, widthPx } from "./theme";
19
19
  * evals at request time (CLAUDE.md §Email: "precompiled, no runtime compile/eval"). Rendering is then
20
20
  * pure string substitution.
21
21
  *
22
- * Tracking is applied here, not in the template: callback tokens are minted ahead of render (signing
22
+ * Tracking is applied here, not in the template: callback tokens are minted ahead of render (sealing
23
23
  * is async; Handlebars helpers are not) and the resulting URLs are placed into the render context.
24
24
  * Click tracking rewrites the declared link locations; open tracking injects a pixel; and an **elective**
25
25
  * template gets an unsubscribe link, which a marketing template additionally cannot render without.
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/email";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.9.0";
16
+ export const PACKAGE_VERSION = "0.10.1";