@pithy-sh/email 0.3.10 → 0.4.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.
@@ -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;AAE7F,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,CAqN/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;AAG7F,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,CAqN/D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
@@ -19,6 +19,7 @@ import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated.js";
19
19
  import { EmailScheduleParams, EmailSendParams } from "./workflows/params.js";
20
20
  import { z } from "zod";
21
21
  import { defineCapability } from "@pithy-sh/core/src/capability/capability";
22
+ import { pithyCommandOf } from "@pithy-sh/core/src/cli/command";
22
23
  import { InternalError } from "@pithy-sh/core/src/error/pithyError";
23
24
  //#region src/capability.ts
24
25
  /**
@@ -221,7 +222,10 @@ function email(config) {
221
222
  const binding = env.EMAIL_SUPPRESSIONS;
222
223
  if (!binding) throw new InternalError({
223
224
  message: "The suppression list is not available.",
224
- action: "Run `pithy add email` to provision it, or bind the EMAIL_SUPPRESSIONS D1 database.",
225
+ action: `Run \`${pithyCommandOf("add", {
226
+ args: ["email"],
227
+ flags: { "--with-prerequisites": true }
228
+ }, { runtime: true })}\` to provision it, or bind the EMAIL_SUPPRESSIONS D1 database.`,
225
229
  detail: "email.suppressions() was called with an env carrying no `EMAIL_SUPPRESSIONS` D1 binding."
226
230
  });
227
231
  return emailSuppressionDatabase(binding);
@@ -1 +1 @@
1
- {"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/http/callbacks.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAGjC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAG9B,MAAM,gBAAgB,CAAC;AA4CxB,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAQD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;CACb;AAgBD,sFAAsF;AACtF,wBAAsB,WAAW,CAC/B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,QAAQ,CAAC,CAmBnB;AAED,uDAAuD;AACvD,wBAAsB,UAAU,CAC9B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,aAAa,EAAE,wBAAwB,EACvC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,QAAQ,CAAC,CAuBnB;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAyC/D"}
1
+ {"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/http/callbacks.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAI7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAGjC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAG9B,MAAM,gBAAgB,CAAC;AA4CxB,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAQD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;CACb;AAgBD,sFAAsF;AACtF,wBAAsB,WAAW,CAC/B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,QAAQ,CAAC,CAmBnB;AAED,uDAAuD;AACvD,wBAAsB,UAAU,CAC9B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,aAAa,EAAE,wBAAwB,EACvC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,QAAQ,CAAC,CAuBnB;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAsE/D"}
@@ -9,8 +9,8 @@ import { verifyToken } from "../crypto/token.js";
9
9
  import { CALLBACK_BASE } from "../templates/engine.js";
10
10
  import { CallbackTokenParam, UnsubscribeQuery } from "./schemas.js";
11
11
  import { normalizeAddress } from "@pithy-sh/core/src/address/address";
12
- import { zValidator } from "@hono/zod-validator";
13
- import { validationHook } from "@pithy-sh/core/src/http/validation";
12
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
13
+ import { validate } from "@pithy-sh/core/src/http/validation";
14
14
  //#region src/http/callbacks.ts
15
15
  /** A 1×1 transparent PNG — the open-tracking pixel body. */
16
16
  const PIXEL = Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg=="), (c) => c.charCodeAt(0));
@@ -97,21 +97,42 @@ function registerCallbacks(app) {
97
97
  keys: { versions: keys.versions }
98
98
  };
99
99
  };
100
- app.get(`${CALLBACK_BASE}/c/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
100
+ app.get(`${CALLBACK_BASE}/c/:token`, describeRoute({
101
+ summary: "Record a click on a tracked link, then send the reader on to it.",
102
+ description: "Public: the HMAC signature on the token is the only gate. A forged, altered, or expired token answers `email/invalid_token` (400) before anything is recorded, and the destination is the http(s) URL signed into the token, never one from the request.",
103
+ verification: "public",
104
+ responses: { 302: { description: "A redirect to the link's destination, carried in `Location`." } }
105
+ }), validate("param", CallbackTokenParam), async (c) => {
101
106
  const { db, keys } = await setup(c.env);
102
107
  return handleClick(db, keys, {
103
108
  token: c.req.valid("param").token,
104
109
  url: c.req.url
105
110
  }, /* @__PURE__ */ new Date());
106
111
  });
107
- app.get(`${CALLBACK_BASE}/o/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
112
+ app.get(`${CALLBACK_BASE}/o/:token`, describeRoute({
113
+ summary: "Record that an email was opened.",
114
+ description: "Public: the HMAC signature on the token is the only gate. The token may carry the `.png` suffix mail clients expect on an image URL.",
115
+ verification: "public",
116
+ responses: { 200: {
117
+ description: "A 1×1 transparent PNG, never cached.",
118
+ contentType: "image/png"
119
+ } }
120
+ }), validate("param", CallbackTokenParam), async (c) => {
108
121
  const { db, keys } = await setup(c.env);
109
122
  return handleOpen(db, keys, {
110
123
  token: c.req.valid("param").token,
111
124
  url: c.req.url
112
125
  }, /* @__PURE__ */ new Date());
113
126
  });
114
- app.on(["GET", "POST"], `${CALLBACK_BASE}/u/:token`, zValidator("param", CallbackTokenParam, validationHook), zValidator("query", UnsubscribeQuery, validationHook), async (c) => {
127
+ app.on(["GET", "POST"], `${CALLBACK_BASE}/u/:token`, describeRoute({
128
+ summary: "Unsubscribe the recipient from everything but the mail they ask for.",
129
+ description: "Public: the HMAC signature on the token is the only gate. Answers GET for the link in the message and POST for one-click unsubscribe. The address joins the suppression list shared by every environment.",
130
+ verification: "public",
131
+ responses: { 200: {
132
+ description: "A short HTML page confirming the opt-out.",
133
+ contentType: "text/html"
134
+ } }
135
+ }), validate("param", CallbackTokenParam), validate("query", UnsubscribeQuery), async (c) => {
115
136
  const env = c.env;
116
137
  const { db, suppressionDb, keys } = await setup(env);
117
138
  return handleUnsubscribe(db, suppressionDb, keys, {
@@ -49,7 +49,7 @@ export interface EmailRouteDeclaration {
49
49
  * Every management route, and how it is gated.
50
50
  *
51
51
  * Exported so a test can assert against the declaration rather than against a middleware count. A count
52
- * proves that *something* runs before the handler — a bare `zValidator` satisfies it — and cannot prove
52
+ * proves that *something* runs before the handler — a bare `validate` satisfies it — and cannot prove
53
53
  * *what*. `routeContract.test.ts` checks this list against the paths Hono actually registered, in both
54
54
  * directions, so a route added without an entry and an entry without a route both fail.
55
55
  */
@@ -1 +1 @@
1
- {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAGrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AA+B1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,yGAAyG;AACzG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,qBAAqB,EAY9D,CAAC;AAaF,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAiDD,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA2R5G"}
1
+ {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAKrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AA+B1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,yGAAyG;AACzG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,qBAAqB,EAY9D,CAAC;AAaF,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAiDD,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA+T5G"}
@@ -8,18 +8,20 @@ import { EmailAuditActions } from "../audit/actions.js";
8
8
  import { getJob, listJobs } from "../jobs/read.js";
9
9
  import { retryJob } from "../jobs/retry.js";
10
10
  import { emailSenderBinding } from "../send/senderBinding.js";
11
+ import { EmailJobResponse, EmailJobRetryResponse, EmailJobsResponse, EmailSuppressResponse, EmailSuppressionsResponse, EmailUnsuppressResponse } from "./responses.js";
11
12
  import { jobDetailView, jobListView, suppressionView } from "./view.js";
12
13
  import { ConflictError, InternalError, NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
13
14
  import { normalizeAddress } from "@pithy-sh/core/src/address/address";
14
- import { zValidator } from "@hono/zod-validator";
15
- import { validationHook } from "@pithy-sh/core/src/http/validation";
15
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
16
+ import { validate } from "@pithy-sh/core/src/http/validation";
16
17
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
18
+ import { migrateStep } from "@pithy-sh/core/src/migrations/migrateStep";
17
19
  //#region src/http/routes.ts
18
20
  /**
19
21
  * Every management route, and how it is gated.
20
22
  *
21
23
  * Exported so a test can assert against the declaration rather than against a middleware count. A count
22
- * proves that *something* runs before the handler — a bare `zValidator` satisfies it — and cannot prove
24
+ * proves that *something* runs before the handler — a bare `validate` satisfies it — and cannot prove
23
25
  * *what*. `routeContract.test.ts` checks this list against the paths Hono actually registered, in both
24
26
  * directions, so a route added without an entry and an entry without a route both fail.
25
27
  */
@@ -72,7 +74,7 @@ function d1(c, binding) {
72
74
  const found = c.env[binding];
73
75
  if (!found) throw new InternalError({
74
76
  message: "Email is not fully configured on this Worker.",
75
- action: `Bind a D1 database named ${binding} in wrangler.jsonc, then run pithy migrate.`,
77
+ action: `Bind a D1 database named ${binding} in wrangler.jsonc, then ${migrateStep(c.env)}.`,
76
78
  detail: `the email management routes require a \`${binding}\` D1 binding; none was present on env`
77
79
  });
78
80
  return found;
@@ -105,7 +107,12 @@ function registerEmailAdminRoutes(options) {
105
107
  const base = options.basePath;
106
108
  const clock = options.now ?? (() => /* @__PURE__ */ new Date());
107
109
  return (app) => {
108
- app.get(`${base}/jobs`, requireControlPlane(EMAIL_JOBS_READ_SCOPE), zValidator("query", JobsQuery, validationHook), async (c) => {
110
+ app.get(`${base}/jobs`, describeRoute({
111
+ summary: "Page through the send log.",
112
+ verification: "control-plane",
113
+ scopes: [EMAIL_JOBS_READ_SCOPE],
114
+ responses: { 200: EmailJobsResponse }
115
+ }), requireControlPlane(EMAIL_JOBS_READ_SCOPE), validate("query", JobsQuery), async (c) => {
109
116
  const query = c.req.valid("query");
110
117
  const who = caller(c);
111
118
  const page = await listJobs(jobs(c), query);
@@ -128,7 +135,12 @@ function registerEmailAdminRoutes(options) {
128
135
  nextCursor: page.nextCursor
129
136
  });
130
137
  });
131
- app.get(`${base}/jobs/:id`, requireControlPlane(EMAIL_JOBS_READ_SCOPE), zValidator("param", JobIdParam, validationHook), async (c) => {
138
+ app.get(`${base}/jobs/:id`, describeRoute({
139
+ summary: "Read one email job in full, recipient included.",
140
+ verification: "control-plane",
141
+ scopes: [EMAIL_JOBS_READ_SCOPE],
142
+ responses: { 200: EmailJobResponse }
143
+ }), requireControlPlane(EMAIL_JOBS_READ_SCOPE), validate("param", JobIdParam), async (c) => {
132
144
  const { id } = c.req.valid("param");
133
145
  const who = caller(c);
134
146
  const job = await getJob(jobs(c), id);
@@ -152,7 +164,12 @@ function registerEmailAdminRoutes(options) {
152
164
  });
153
165
  return c.json({ job: jobDetailView(job) });
154
166
  });
155
- app.post(`${base}/jobs/:id/retry`, requireControlPlane(EMAIL_JOBS_RETRY_SCOPE), zValidator("param", JobIdParam, validationHook), async (c) => {
167
+ app.post(`${base}/jobs/:id/retry`, describeRoute({
168
+ summary: "Queue a job to send again.",
169
+ verification: "control-plane",
170
+ scopes: [EMAIL_JOBS_RETRY_SCOPE],
171
+ responses: { 200: EmailJobRetryResponse }
172
+ }), requireControlPlane(EMAIL_JOBS_RETRY_SCOPE), validate("param", JobIdParam), async (c) => {
156
173
  const { id } = c.req.valid("param");
157
174
  const who = caller(c);
158
175
  const now = clock();
@@ -184,7 +201,12 @@ function registerEmailAdminRoutes(options) {
184
201
  dispatched: result.dispatched
185
202
  });
186
203
  });
187
- app.get(`${base}/suppressions`, requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE), zValidator("query", SuppressionsQuery, validationHook), async (c) => {
204
+ app.get(`${base}/suppressions`, describeRoute({
205
+ summary: "Page through the suppression list, or look one address up.",
206
+ verification: "control-plane",
207
+ scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
208
+ responses: { 200: EmailSuppressionsResponse }
209
+ }), requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE), validate("query", SuppressionsQuery), async (c) => {
188
210
  const query = c.req.valid("query");
189
211
  const who = caller(c);
190
212
  const now = clock();
@@ -209,7 +231,12 @@ function registerEmailAdminRoutes(options) {
209
231
  nextCursor: page.nextCursor
210
232
  });
211
233
  });
212
- app.post(`${base}/suppressions`, requireControlPlane(EMAIL_SUPPRESSIONS_WRITE_SCOPE), zValidator("json", SuppressRequest, validationHook), async (c) => {
234
+ app.post(`${base}/suppressions`, describeRoute({
235
+ summary: "Block an address by hand.",
236
+ verification: "control-plane",
237
+ scopes: [EMAIL_SUPPRESSIONS_WRITE_SCOPE],
238
+ responses: { 200: EmailSuppressResponse }
239
+ }), requireControlPlane(EMAIL_SUPPRESSIONS_WRITE_SCOPE), validate("json", SuppressRequest), async (c) => {
213
240
  const input = c.req.valid("json");
214
241
  const who = caller(c);
215
242
  const now = clock();
@@ -258,7 +285,12 @@ function registerEmailAdminRoutes(options) {
258
285
  });
259
286
  return c.json({ suppression: row ? suppressionView(row, now) : null }, 200);
260
287
  });
261
- app.post(`${base}/suppressions/remove`, requireControlPlane(EMAIL_SUPPRESSIONS_DELETE_SCOPE), zValidator("json", UnsuppressRequest, validationHook), async (c) => {
288
+ app.post(`${base}/suppressions/remove`, describeRoute({
289
+ summary: "Lift the block on an address.",
290
+ verification: "control-plane",
291
+ scopes: [EMAIL_SUPPRESSIONS_DELETE_SCOPE],
292
+ responses: { 200: EmailUnsuppressResponse }
293
+ }), requireControlPlane(EMAIL_SUPPRESSIONS_DELETE_SCOPE), validate("json", UnsuppressRequest), async (c) => {
262
294
  const input = c.req.valid("json");
263
295
  const who = caller(c);
264
296
  const email = normalizeAddress(input.email);
@@ -91,9 +91,13 @@ export interface EmailProvisioner {
91
91
  * Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
92
92
  */
93
93
  preflight(): Promise<void>;
94
- /** Create (or reuse) the project's suppression D1; returns its id. Idempotent. Runs once, before any env. */
94
+ /**
95
+ * Create (or reuse) the project's suppression D1; returns its id, and whether this call created it. Idempotent.
96
+ * Runs once, before any env.
97
+ */
95
98
  ensureSuppressionDatabase(): Promise<{
96
99
  databaseId: string;
100
+ created: boolean;
97
101
  }>;
98
102
  /** Run the `email_0001_suppressions` migration against the suppression D1. Idempotent (applied ones skip). */
99
103
  migrateSuppression(databaseId: string): Promise<void>;
@@ -113,6 +117,8 @@ export interface EmailProvisioner {
113
117
  /** What provisioning produced. */
114
118
  export interface EmailProvisionResult {
115
119
  suppressionDatabaseId: string;
120
+ /** Whether this run created the suppression database, or found one an earlier run made. */
121
+ suppressionDatabaseCreated: boolean;
116
122
  environments: ManagedEnvironment[];
117
123
  /** Whether the inbound routing rule was created, already present, or skipped (not configured). */
118
124
  routing: {
@@ -1 +1 @@
1
- {"version":3,"file":"provisionEmail.d.ts","sourceRoot":"","sources":["../../src/provision/provisionEmail.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAKlF,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,kGAAkG;AAClG,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAW/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAEhF;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,6GAA6G;IAC7G,yBAAyB,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,8GAA8G;IAC9G,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sHAAsH;IACtH,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACnC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,kGAAkG;IAClG,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAc/B;AAED,0HAA0H;AAC1H,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,wBAAwB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACpD;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,+EAA+E;IAC/E,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;;OAKG;IACH,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,+GAA+G;AAC/G,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,kBAAkB,EACjC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC;IAAE,GAAG,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAgBtC"}
1
+ {"version":3,"file":"provisionEmail.d.ts","sourceRoot":"","sources":["../../src/provision/provisionEmail.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAKlF,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,kGAAkG;AAClG,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAW/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAEhF;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B;;;OAGG;IACH,yBAAyB,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC/E,8GAA8G;IAC9G,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sHAAsH;IACtH,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACnC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2FAA2F;IAC3F,0BAA0B,EAAE,OAAO,CAAC;IACpC,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,kGAAkG;IAClG,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAc/B;AAED,0HAA0H;AAC1H,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,wBAAwB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACpD;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,+EAA+E;IAC/E,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;;OAKG;IACH,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,+GAA+G;AAC/G,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,kBAAkB,EACjC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC;IAAE,GAAG,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAgBtC"}
@@ -121,12 +121,13 @@ function emailWorkerName(project, env) {
121
121
  */
122
122
  async function provisionEmail(provisioner, environments) {
123
123
  await provisioner.preflight();
124
- const { databaseId } = await provisioner.ensureSuppressionDatabase();
124
+ const { databaseId, created } = await provisioner.ensureSuppressionDatabase();
125
125
  await provisioner.migrateSuppression(databaseId);
126
126
  const deployed = managedEnvironments(environments);
127
127
  for (const env of deployed) await provisioner.deployWorker(env, databaseId);
128
128
  return {
129
129
  suppressionDatabaseId: databaseId,
130
+ suppressionDatabaseCreated: created,
130
131
  environments: deployed,
131
132
  routing: deployed.length > 0 ? await provisioner.ensureRoutingRule() : {
132
133
  created: false,
@@ -1 +1 @@
1
- {"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;AAMhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AA2ND,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAK5E"}
1
+ {"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;AAOhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AA6PD,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAS5E"}
@@ -1,8 +1,9 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey.js";
4
- import { emailHostEnv } from "../workflows/hostEnv.js";
4
+ import { EMAIL_PROVISION, emailHostEnv } from "../workflows/hostEnv.js";
5
5
  import { suppressionDatabaseName } from "./provisionEmail.js";
6
+ import { personDecision, pithyCommand, remedy, workerDirOf } from "@pithy-sh/core/src/cli/command";
6
7
  import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
7
8
  import "@pithy-sh/core/src/naming/domains";
8
9
  import { environmentScope } from "@pithy-sh/core/src/naming/provisionScope";
@@ -54,13 +55,39 @@ function originOf(url) {
54
55
  * config object per Worker, so a `BASE_URL` that is not a URL is one edit however many environments a
55
56
  * project declares. Three lines about one key is how a report stops being read.
56
57
  */
57
- function localHostEnv(config) {
58
+ function localHostEnv(config, workerDirectory) {
58
59
  const candidate = {
59
60
  ...stubBindings(),
60
61
  BASE_URL: config.baseUrl,
61
62
  ...config.theme ? { EMAIL_THEME: JSON.stringify(config.theme) } : {}
62
63
  };
63
- return hostEnvFindings(checkHostEnv(emailHostEnv, candidate), null);
64
+ return hostEnvFindings(forWorker(checkHostEnv(emailHostEnv, candidate), workerDirectory), null);
65
+ }
66
+ /**
67
+ * **`pithy email provision` for the Worker this check ran for (#711).** It acts on one Worker, and in a project
68
+ * with several a bare one is refused `input/required`. Takes the Worker's `apps/` directory, which is what
69
+ * `--worker` takes and what that refusal lists. Not its `wrangler.jsonc` name: a scaffold deploys `apps/api` as
70
+ * `acme-api`.
71
+ */
72
+ function provisionCommand(workerDirectory) {
73
+ return pithyCommand("email provision", { flags: { "--worker": workerDirOf({ dir: workerDirectory }) } });
74
+ }
75
+ /**
76
+ * The host's own report, with its provisioning command named for this Worker by its `apps/` directory. The host
77
+ * writes the bare command into its log because it cannot know the Worker; a check that does know names it, in
78
+ * the action and the `fix` alike.
79
+ */
80
+ function forWorker(report, workerDirectory) {
81
+ return {
82
+ ...report,
83
+ problems: report.problems.map((problem) => problem.provider.command === EMAIL_PROVISION ? {
84
+ ...problem,
85
+ provider: {
86
+ ...problem.provider,
87
+ command: provisionCommand(workerDirectory)
88
+ }
89
+ } : problem)
90
+ };
64
91
  }
65
92
  /**
66
93
  * Whether a URL points at this machine — {@link LOCAL_ORIGIN} and every spelling of it, port or none.
@@ -141,7 +168,8 @@ async function accountFindings(config, context) {
141
168
  setting: "EMAIL_SUPPRESSIONS",
142
169
  environment: null,
143
170
  problem: `No D1 database named ${suppressions} exists on this account.`,
144
- action: "Run `pithy email provision`. Nothing is suppressed until it exists."
171
+ action: `Run \`${provisionCommand(context.workerDirectory)}\`. Nothing is suppressed until it exists.`,
172
+ fix: provisionCommand(context.workerDirectory)
145
173
  });
146
174
  for (const environment of context.environments) {
147
175
  if (environment.name === "dev") continue;
@@ -165,6 +193,8 @@ async function accountFindings(config, context) {
165
193
  * **What this sees:** a row under this registry name. A secret some other declaration moved off D1 has its
166
194
  * own check to write, or none; nothing here walks the vault for strays, because the vault cannot be listed.
167
195
  */
196
+ /** What creates a missing link-signing entry: a provision of every environment, production included (#711). */
197
+ const PROVISION_SECRETS = remedy("secrets provision");
168
198
  async function signingKeyFindings(context, environment) {
169
199
  const findings = [];
170
200
  const entry = environmentScope(context.project, environment).secretEntry(EMAIL_LINK_SIGNING_KEY, emailSigningRegistry[EMAIL_LINK_SIGNING_KEY].scope);
@@ -172,7 +202,8 @@ async function signingKeyFindings(context, environment) {
172
202
  setting: EMAIL_LINK_SIGNING_KEY,
173
203
  environment,
174
204
  problem: `The link-signing key has no Secrets Store entry in ${environment}, so no tracking or unsubscribe link can be signed.`,
175
- action: "Run `pithy secrets provision`."
205
+ action: PROVISION_SECRETS.say((command) => `Run \`${command}\`.`),
206
+ ...PROVISION_SECRETS.fix === void 0 ? {} : { fix: PROVISION_SECRETS.fix }
176
207
  });
177
208
  if (await context.account.vaultSecret({
178
209
  name: "email-link-signing-key",
@@ -181,7 +212,13 @@ async function signingKeyFindings(context, environment) {
181
212
  setting: EMAIL_LINK_SIGNING_KEY,
182
213
  environment,
183
214
  problem: `The link-signing key is still held in ${environment}'s D1 vault, where nothing reads it. Links signed with it before the move no longer verify.`,
184
- action: `Once the Secrets Store entry is bound and deployed, run \`pithy secrets rm ${EMAIL_LINK_SIGNING_KEY} --env ${environment} --backend d1\`. See docs/commands/secrets.md#moving-a-secret-off-d1.`
215
+ action: `Once the Secrets Store entry is bound and deployed, the D1 copy can go: ${personDecision("secrets rm", {
216
+ args: [EMAIL_LINK_SIGNING_KEY],
217
+ flags: {
218
+ "--env": environment,
219
+ "--backend": "d1"
220
+ }
221
+ })} See docs/commands/secrets.md#moving-a-secret-off-d1.`
185
222
  });
186
223
  return findings;
187
224
  }
@@ -189,7 +226,7 @@ async function signingKeyFindings(context, environment) {
189
226
  function emailSettings(config) {
190
227
  return {
191
228
  local: (context) => [
192
- ...localHostEnv(config),
229
+ ...localHostEnv(config, context.workerDirectory),
193
230
  ...localForAddress(config),
194
231
  ...localBaseUrlOrigin(config, context)
195
232
  ],
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/email";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.3.10";
6
+ export declare const PACKAGE_VERSION = "0.4.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,oFAAoF;AACpF,eAAO,MAAM,eAAe,WAAW,CAAC"}
1
+ {"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/email";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.3.10";
7
+ const PACKAGE_VERSION = "0.4.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
@@ -5,6 +5,47 @@ import type { SecretBinding } from "@pithy-sh/secrets/src/env/bindings";
5
5
  import { z } from "zod";
6
6
  import type { EmailSender } from "../send/sender";
7
7
  import type { SendWorkflowInstances } from "./instances";
8
+ /**
9
+ * What the prebuilt email host worker reads out of its env — declared once, validated at boot, and
10
+ * read statically by `pithy doctor` (pithy-sh/pithy#410, #411).
11
+ *
12
+ * Nobody authors this Worker. `pithy email provision` resolves the committed template beside this
13
+ * file and deploys it, so every value here arrives as a binding, a var or a Secrets Store entry that
14
+ * a *machine* wrote — and until this module, none of it was checked. Three failures, all of them
15
+ * discovered as mail that did not arrive:
16
+ *
17
+ * - `BASE_URL` absent → every magic link in the batch pointed at `undefined/auth/…`.
18
+ * - `EMAIL_THEME` unparseable → a `JSON.parse` threw inside a render step, three retries deep,
19
+ * where the message reads as a template fault.
20
+ * - `SCHEDULER_BATCH_SIZE` written `"fifty"` → `Number(...)` gave `NaN`, the scheduler claimed
21
+ * nothing, and it did so on every tick, forever, without a line in the log.
22
+ *
23
+ * So the parse is the boot check: `z.output` is what the host actually runs on, which is why the
24
+ * coercions live in the schema rather than at the call sites. `Number(env.MAX_ATTEMPTS ?? 5)` in
25
+ * `worker.ts` was the shape of the bug — a default and a coercion restated at every reader, each free
26
+ * to disagree with the next.
27
+ *
28
+ * ## Two names, deliberately
29
+ *
30
+ * {@link EmailHostEnv} is the schema (and the type the host runs on). {@link emailHostEnv} is the
31
+ * *declaration*: the schema plus what fills each field, which is the object the CLI imports. The
32
+ * second is the one an operator's report is built from — a missing field is only actionable when
33
+ * something names the binding, var or command that writes it.
34
+ *
35
+ * Node-safe on purpose. No `cloudflare:` import and no filesystem, so `pithy doctor` can import this
36
+ * without executing the Worker — the same constraint `@pithy-sh/core`'s host modules carry.
37
+ */
38
+ /**
39
+ * The command that writes every provisioned value here. Stated once so nine action lines cannot drift.
40
+ *
41
+ * No `--env`: it spans every declared environment in one run and declares no such flag, and a flag a
42
+ * command does not declare is refused (#594) — so a remedy naming one is a remedy that cannot be followed.
43
+ *
44
+ * No `--worker` either, and only here: this is the sentence the deployed host writes into its own log, and
45
+ * a host does not know which app Worker's `apps/` directory provisioned it. `pithy doctor` reports the same
46
+ * finding for a Worker it knows, and names it there (`provision/settingsCheck.ts`, #711).
47
+ */
48
+ export declare const EMAIL_PROVISION: import("@pithy-sh/core/src/cli/command").Command;
8
49
  /** The email host's env, as the host runs on it. Every field is coerced here, never at its reader. */
9
50
  export declare const EmailHostEnv: z.ZodObject<{
10
51
  DB: z.ZodType<D1Database, unknown, z.core.$ZodTypeInternals<D1Database, unknown>>;
@@ -1 +1 @@
1
- {"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflows/hostEnv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAgFzD,sGAAsG;AACtG,eAAO,MAAM,YAAY;;;;;;;;;kBA+BiB,OAAO,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4D6C,CAAC;AACxG,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,kGAAkG;AAClG,KAAK,kBAAkB,GAAG;IACxB,MAAM,CAAC,OAAO,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,EAAE,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClF,GAAG,qBAAqB,CAAC;AAO1B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;kBAhFiB,OAAO,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsHxD,CAAC"}
1
+ {"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflows/hostEnv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,kDAA2D,CAAC;AA2CxF,sGAAsG;AACtG,eAAO,MAAM,YAAY;;;;;;;;;kBA+BiB,OAAO,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4D6C,CAAC;AACxG,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,kGAAkG;AAClG,KAAK,kBAAkB,GAAG;IACxB,MAAM,CAAC,OAAO,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,EAAE,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClF,GAAG,qBAAqB,CAAC;AAO1B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;kBAhFiB,OAAO,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsHxD,CAAC"}
@@ -3,6 +3,7 @@
3
3
  import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING } from "../crypto/signingKey.js";
4
4
  import { EmailTheme, defaultTheme } from "../templates/theme.js";
5
5
  import { z } from "zod";
6
+ import { pithyCommandOf, remedy } from "@pithy-sh/core/src/cli/command";
6
7
  import { defineHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
7
8
  //#region src/workflows/hostEnv.ts
8
9
  /**
@@ -40,13 +41,19 @@ import { defineHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
40
41
  *
41
42
  * No `--env`: it spans every declared environment in one run and declares no such flag, and a flag a
42
43
  * command does not declare is refused (#594) — so a remedy naming one is a remedy that cannot be followed.
44
+ *
45
+ * No `--worker` either, and only here: this is the sentence the deployed host writes into its own log, and
46
+ * a host does not know which app Worker's `apps/` directory provisioned it. `pithy doctor` reports the same
47
+ * finding for a Worker it knows, and names it there (`provision/settingsCheck.ts`, #711).
43
48
  */
44
- const PROVISION = "pithy email provision";
49
+ const EMAIL_PROVISION = pithyCommandOf("email provision", {}, { runtime: true });
50
+ const PROVISION = EMAIL_PROVISION;
45
51
  /**
46
- * The command that writes both host secrets below. No `--env`, for the same reason: `pithy secrets provision`
47
- * provisions every declared environment in one run and declares no such flag.
52
+ * What writes both host secrets below, said as a person's decision. No `--env`, for the same reason: `pithy secrets
53
+ * provision` provisions every declared environment in one run, production included, and declares no such flag — so
54
+ * it is never a `Run` line for one host's secret (#711).
48
55
  */
49
- const SECRETS_PROVISION = "pithy secrets provision";
56
+ const SECRETS_PROVISION = remedy("secrets provision", {}, { runtime: true }).say((command) => command);
50
57
  /** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
51
58
  const binding = (name) => ({
52
59
  kind: "binding",
@@ -136,12 +143,12 @@ const emailHostEnv = defineHostEnv({
136
143
  SECRETS_ENCRYPTION_KEYS: {
137
144
  kind: "secret",
138
145
  name: "SECRETS_ENCRYPTION_KEYS",
139
- command: SECRETS_PROVISION
146
+ decision: SECRETS_PROVISION
140
147
  },
141
148
  [EMAIL_LINK_SIGNING_KEY_BINDING]: {
142
149
  kind: "secret",
143
150
  name: EMAIL_LINK_SIGNING_KEY,
144
- command: SECRETS_PROVISION
151
+ decision: SECRETS_PROVISION
145
152
  },
146
153
  EMAIL: binding("EMAIL"),
147
154
  EMAIL_SENDER: binding("EMAIL_SENDER"),
@@ -163,4 +170,4 @@ const emailHostEnv = defineHostEnv({
163
170
  }
164
171
  });
165
172
  //#endregion
166
- export { EmailHostEnv, emailHostEnv };
173
+ export { EMAIL_PROVISION, EmailHostEnv, emailHostEnv };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/email",
3
- "version": "0.3.10",
3
+ "version": "0.4.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -42,14 +42,14 @@
42
42
  "postal-mime": "^3.0.0"
43
43
  },
44
44
  "peerDependencies": {
45
- "@pithy-sh/core": "^0.8.0",
46
- "@pithy-sh/secrets": "^0.3.1",
45
+ "@pithy-sh/core": "^0.10.0",
46
+ "@pithy-sh/secrets": "^0.4.0",
47
47
  "hono": "^4.13.2",
48
48
  "kysely": "^0.29.0",
49
49
  "zod": "^4.4.0"
50
50
  },
51
51
  "devDependencies": {
52
- "@cloudflare/vitest-plugin": "^1.0.0",
52
+ "@cloudflare/vitest-plugin": "^1.4.2",
53
53
  "@pithy-sh/cloudflare": "workspace:*",
54
54
  "@pithy-sh/core": "workspace:*",
55
55
  "@pithy-sh/secrets": "workspace:*",
@@ -62,7 +62,7 @@
62
62
  "tsdown": "^0.23.0",
63
63
  "typescript": "^7.0.2",
64
64
  "vitest": "^4.1.0",
65
- "wrangler": "^4.115.0",
65
+ "wrangler": "^4.151.0",
66
66
  "zod": "^4.4.0"
67
67
  }
68
68
  }
package/src/capability.ts CHANGED
@@ -3,6 +3,7 @@
3
3
 
4
4
  import type { D1Database } from "@cloudflare/workers-types";
5
5
  import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
6
+ import { pithyCommandOf } from "@pithy-sh/core/src/cli/command";
6
7
  import { InternalError } from "@pithy-sh/core/src/error/pithyError";
7
8
  import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
8
9
  import { z } from "zod";
@@ -345,7 +346,7 @@ export function email(config: EmailConfigInput): EmailCapability {
345
346
  if (!binding) {
346
347
  throw new InternalError({
347
348
  message: "The suppression list is not available.",
348
- action: "Run `pithy add email` to provision it, or bind the EMAIL_SUPPRESSIONS D1 database.",
349
+ action: `Run \`${pithyCommandOf("add", { args: ["email"], flags: { "--with-prerequisites": true } }, { runtime: true })}\` to provision it, or bind the EMAIL_SUPPRESSIONS D1 database.`,
349
350
  detail: "email.suppressions() was called with an env carrying no `EMAIL_SUPPRESSIONS` D1 binding.",
350
351
  });
351
352
  }
@@ -2,10 +2,10 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
4
  import type { D1Database } from "@cloudflare/workers-types";
5
- import { zValidator } from "@hono/zod-validator";
6
5
  import { normalizeAddress } from "@pithy-sh/core/src/address/address";
7
6
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
8
- import { validationHook } from "@pithy-sh/core/src/http/validation";
7
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
8
+ import { validate } from "@pithy-sh/core/src/http/validation";
9
9
  import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
10
10
  import type { Hono } from "hono";
11
11
  import { resolveSigningKeys } from "../crypto/signingKey";
@@ -202,21 +202,50 @@ export function registerCallbacks(app: Hono<PithyHonoEnv>): void {
202
202
  };
203
203
  };
204
204
 
205
- app.get(`${CALLBACK_BASE}/c/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
206
- const { db, keys } = await setup(c.env as unknown as CallbackEnv);
207
- return handleClick(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
208
- });
205
+ app.get(
206
+ `${CALLBACK_BASE}/c/:token`,
207
+ describeRoute({
208
+ summary: "Record a click on a tracked link, then send the reader on to it.",
209
+ description:
210
+ "Public: the HMAC signature on the token is the only gate. A forged, altered, or expired token answers `email/invalid_token` (400) before anything is recorded, and the destination is the http(s) URL signed into the token, never one from the request.",
211
+ verification: "public",
212
+ responses: { 302: { description: "A redirect to the link's destination, carried in `Location`." } },
213
+ }),
214
+ validate("param", CallbackTokenParam),
215
+ async (c) => {
216
+ const { db, keys } = await setup(c.env as unknown as CallbackEnv);
217
+ return handleClick(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
218
+ },
219
+ );
209
220
 
210
- app.get(`${CALLBACK_BASE}/o/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
211
- const { db, keys } = await setup(c.env as unknown as CallbackEnv);
212
- return handleOpen(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
213
- });
221
+ app.get(
222
+ `${CALLBACK_BASE}/o/:token`,
223
+ describeRoute({
224
+ summary: "Record that an email was opened.",
225
+ description:
226
+ "Public: the HMAC signature on the token is the only gate. The token may carry the `.png` suffix mail clients expect on an image URL.",
227
+ verification: "public",
228
+ responses: { 200: { description: "A 1×1 transparent PNG, never cached.", contentType: "image/png" } },
229
+ }),
230
+ validate("param", CallbackTokenParam),
231
+ async (c) => {
232
+ const { db, keys } = await setup(c.env as unknown as CallbackEnv);
233
+ return handleOpen(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
234
+ },
235
+ );
214
236
 
215
237
  app.on(
216
238
  ["GET", "POST"],
217
239
  `${CALLBACK_BASE}/u/:token`,
218
- zValidator("param", CallbackTokenParam, validationHook),
219
- zValidator("query", UnsubscribeQuery, validationHook),
240
+ describeRoute({
241
+ summary: "Unsubscribe the recipient from everything but the mail they ask for.",
242
+ description:
243
+ "Public: the HMAC signature on the token is the only gate. Answers GET for the link in the message and POST for one-click unsubscribe. The address joins the suppression list shared by every environment.",
244
+ verification: "public",
245
+ responses: { 200: { description: "A short HTML page confirming the opt-out.", contentType: "text/html" } },
246
+ }),
247
+ validate("param", CallbackTokenParam),
248
+ validate("query", UnsubscribeQuery),
220
249
  async (c) => {
221
250
  const env = c.env as unknown as CallbackEnv;
222
251
  const { db, suppressionDb, keys } = await setup(env);
@@ -2,15 +2,17 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
4
  import type { D1Database } from "@cloudflare/workers-types";
5
- import { zValidator } from "@hono/zod-validator";
6
5
  import { normalizeAddress } from "@pithy-sh/core/src/address/address";
7
6
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
8
7
  import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
9
8
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
10
9
  import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
10
+ import type { AmbientEnv } from "@pithy-sh/core/src/env/ambient";
11
11
  import { ConflictError, InternalError, NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
12
- import { validationHook } from "@pithy-sh/core/src/http/validation";
12
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
13
+ import { validate } from "@pithy-sh/core/src/http/validation";
13
14
  import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
15
+ import { migrateStep } from "@pithy-sh/core/src/migrations/migrateStep";
14
16
  import type { Context, Hono } from "hono";
15
17
  import { EmailAuditActions } from "../audit/actions";
16
18
  import {
@@ -31,7 +33,7 @@ import {
31
33
  EMAIL_SUPPRESSIONS_READ_SCOPE,
32
34
  EMAIL_SUPPRESSIONS_WRITE_SCOPE,
33
35
  } from "./guards";
34
- import type {
36
+ import {
35
37
  EmailJobResponse,
36
38
  EmailJobRetryResponse,
37
39
  EmailJobsResponse,
@@ -89,7 +91,7 @@ export interface EmailRouteDeclaration {
89
91
  * Every management route, and how it is gated.
90
92
  *
91
93
  * Exported so a test can assert against the declaration rather than against a middleware count. A count
92
- * proves that *something* runs before the handler — a bare `zValidator` satisfies it — and cannot prove
94
+ * proves that *something* runs before the handler — a bare `validate` satisfies it — and cannot prove
93
95
  * *what*. `routeContract.test.ts` checks this list against the paths Hono actually registered, in both
94
96
  * directions, so a route added without an entry and an entry without a route both fail.
95
97
  */
@@ -145,7 +147,7 @@ function d1(c: Context<PithyHonoEnv>, binding: "DB" | "EMAIL_SUPPRESSIONS"): D1D
145
147
  if (!found) {
146
148
  throw new InternalError({
147
149
  message: "Email is not fully configured on this Worker.",
148
- action: `Bind a D1 database named ${binding} in wrangler.jsonc, then run pithy migrate.`,
150
+ action: `Bind a D1 database named ${binding} in wrangler.jsonc, then ${migrateStep(c.env as AmbientEnv)}.`,
149
151
  detail: `the email management routes require a \`${binding}\` D1 binding; none was present on env`,
150
152
  });
151
153
  }
@@ -190,8 +192,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
190
192
 
191
193
  app.get(
192
194
  `${base}/jobs`,
195
+ describeRoute({
196
+ summary: "Page through the send log.",
197
+ verification: "control-plane",
198
+ scopes: [EMAIL_JOBS_READ_SCOPE],
199
+ responses: { 200: EmailJobsResponse },
200
+ }),
193
201
  requireControlPlane(EMAIL_JOBS_READ_SCOPE),
194
- zValidator("query", JobsQuery, validationHook),
202
+ validate("query", JobsQuery),
195
203
  async (c) => {
196
204
  const query = c.req.valid("query");
197
205
  const who = caller(c);
@@ -221,8 +229,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
221
229
 
222
230
  app.get(
223
231
  `${base}/jobs/:id`,
232
+ describeRoute({
233
+ summary: "Read one email job in full, recipient included.",
234
+ verification: "control-plane",
235
+ scopes: [EMAIL_JOBS_READ_SCOPE],
236
+ responses: { 200: EmailJobResponse },
237
+ }),
224
238
  requireControlPlane(EMAIL_JOBS_READ_SCOPE),
225
- zValidator("param", JobIdParam, validationHook),
239
+ validate("param", JobIdParam),
226
240
  async (c) => {
227
241
  const { id } = c.req.valid("param");
228
242
  const who = caller(c);
@@ -254,8 +268,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
254
268
 
255
269
  app.post(
256
270
  `${base}/jobs/:id/retry`,
271
+ describeRoute({
272
+ summary: "Queue a job to send again.",
273
+ verification: "control-plane",
274
+ scopes: [EMAIL_JOBS_RETRY_SCOPE],
275
+ responses: { 200: EmailJobRetryResponse },
276
+ }),
257
277
  requireControlPlane(EMAIL_JOBS_RETRY_SCOPE),
258
- zValidator("param", JobIdParam, validationHook),
278
+ validate("param", JobIdParam),
259
279
  async (c) => {
260
280
  const { id } = c.req.valid("param");
261
281
  const who = caller(c);
@@ -297,8 +317,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
297
317
 
298
318
  app.get(
299
319
  `${base}/suppressions`,
320
+ describeRoute({
321
+ summary: "Page through the suppression list, or look one address up.",
322
+ verification: "control-plane",
323
+ scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
324
+ responses: { 200: EmailSuppressionsResponse },
325
+ }),
300
326
  requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE),
301
- zValidator("query", SuppressionsQuery, validationHook),
327
+ validate("query", SuppressionsQuery),
302
328
  async (c) => {
303
329
  const query = c.req.valid("query");
304
330
  const who = caller(c);
@@ -333,8 +359,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
333
359
 
334
360
  app.post(
335
361
  `${base}/suppressions`,
362
+ describeRoute({
363
+ summary: "Block an address by hand.",
364
+ verification: "control-plane",
365
+ scopes: [EMAIL_SUPPRESSIONS_WRITE_SCOPE],
366
+ responses: { 200: EmailSuppressResponse },
367
+ }),
336
368
  requireControlPlane(EMAIL_SUPPRESSIONS_WRITE_SCOPE),
337
- zValidator("json", SuppressRequest, validationHook),
369
+ validate("json", SuppressRequest),
338
370
  async (c) => {
339
371
  const input = c.req.valid("json");
340
372
  const who = caller(c);
@@ -425,8 +457,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
425
457
 
426
458
  app.post(
427
459
  `${base}/suppressions/remove`,
460
+ describeRoute({
461
+ summary: "Lift the block on an address.",
462
+ verification: "control-plane",
463
+ scopes: [EMAIL_SUPPRESSIONS_DELETE_SCOPE],
464
+ responses: { 200: EmailUnsuppressResponse },
465
+ }),
428
466
  requireControlPlane(EMAIL_SUPPRESSIONS_DELETE_SCOPE),
429
- zValidator("json", UnsuppressRequest, validationHook),
467
+ validate("json", UnsuppressRequest),
430
468
  async (c) => {
431
469
  const input = c.req.valid("json");
432
470
  const who = caller(c);
@@ -8,7 +8,7 @@ import { EmailJobStatus, SuppressionReason } from "../data/enums";
8
8
  /**
9
9
  * The request schemas for every email route — the three public callbacks and the six control-plane
10
10
  * admin routes. Validation happens at the HTTP boundary (CLAUDE.md §Zod), declared on the route line
11
- * with `zValidator(target, Schema, validationHook)` — so reading `callbacks.ts` or `routes.ts` tells
11
+ * with `validate(target, Schema)` — so reading `callbacks.ts` or `routes.ts` tells
12
12
  * you what each route accepts without opening a handler.
13
13
  *
14
14
  * The callback schemas bound a value that already reaches the handler as free-form text. Neither tries
@@ -124,8 +124,11 @@ export interface EmailProvisioner {
124
124
  * Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
125
125
  */
126
126
  preflight(): Promise<void>;
127
- /** Create (or reuse) the project's suppression D1; returns its id. Idempotent. Runs once, before any env. */
128
- ensureSuppressionDatabase(): Promise<{ databaseId: string }>;
127
+ /**
128
+ * Create (or reuse) the project's suppression D1; returns its id, and whether this call created it. Idempotent.
129
+ * Runs once, before any env.
130
+ */
131
+ ensureSuppressionDatabase(): Promise<{ databaseId: string; created: boolean }>;
129
132
  /** Run the `email_0001_suppressions` migration against the suppression D1. Idempotent (applied ones skip). */
130
133
  migrateSuppression(databaseId: string): Promise<void>;
131
134
  /** Deploy the prebuilt email worker for this environment, wired to the suppression DB and the env's own resources. */
@@ -142,6 +145,8 @@ export interface EmailProvisioner {
142
145
  /** What provisioning produced. */
143
146
  export interface EmailProvisionResult {
144
147
  suppressionDatabaseId: string;
148
+ /** Whether this run created the suppression database, or found one an earlier run made. */
149
+ suppressionDatabaseCreated: boolean;
145
150
  environments: ManagedEnvironment[];
146
151
  /** Whether the inbound routing rule was created, already present, or skipped (not configured). */
147
152
  routing: { created: boolean; skipped: boolean };
@@ -166,7 +171,7 @@ export async function provisionEmail(
166
171
  environments: DeclaredEnvironments | readonly string[],
167
172
  ): Promise<EmailProvisionResult> {
168
173
  await provisioner.preflight();
169
- const { databaseId } = await provisioner.ensureSuppressionDatabase();
174
+ const { databaseId, created } = await provisioner.ensureSuppressionDatabase();
170
175
  await provisioner.migrateSuppression(databaseId);
171
176
  const deployed = managedEnvironments(environments);
172
177
  for (const env of deployed) {
@@ -177,7 +182,7 @@ export async function provisionEmail(
177
182
  // was never deployed, which is the window this ordering exists to close.
178
183
  const routing =
179
184
  deployed.length > 0 ? await provisioner.ensureRoutingRule() : { created: false, skipped: true as const };
180
- return { suppressionDatabaseId: databaseId, environments: deployed, routing };
185
+ return { suppressionDatabaseId: databaseId, suppressionDatabaseCreated: created, environments: deployed, routing };
181
186
  }
182
187
 
183
188
  /** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
@@ -9,12 +9,13 @@ import type {
9
9
  SettingsFinding,
10
10
  } from "@pithy-sh/core/src/capability/settings";
11
11
  import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
12
+ import { type Command, personDecision, pithyCommand, remedy, workerDirOf } from "@pithy-sh/core/src/cli/command";
12
13
  import { LOCAL_ORIGIN } from "@pithy-sh/core/src/naming/domains";
13
14
  import { environmentScope, type SecretNameScope } from "@pithy-sh/core/src/naming/provisionScope";
14
- import { checkHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
15
+ import { checkHostEnv, type HostEnvReport } from "@pithy-sh/core/src/workflow/hostEnv";
15
16
  import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey";
16
17
  import type { EmailTheme } from "../templates/theme";
17
- import { emailHostEnv } from "../workflows/hostEnv";
18
+ import { EMAIL_PROVISION, emailHostEnv } from "../workflows/hostEnv";
18
19
  import { suppressionDatabaseName } from "./provisionEmail";
19
20
 
20
21
  /**
@@ -103,7 +104,7 @@ function originOf(url: string): string | null {
103
104
  * config object per Worker, so a `BASE_URL` that is not a URL is one edit however many environments a
104
105
  * project declares. Three lines about one key is how a report stops being read.
105
106
  */
106
- function localHostEnv(config: EmailSettingsInput): SettingsFinding[] {
107
+ function localHostEnv(config: EmailSettingsInput, workerDirectory: string): SettingsFinding[] {
107
108
  const candidate = {
108
109
  ...stubBindings(),
109
110
  BASE_URL: config.baseUrl,
@@ -112,7 +113,33 @@ function localHostEnv(config: EmailSettingsInput): SettingsFinding[] {
112
113
  // failure this catches.
113
114
  ...(config.theme ? { EMAIL_THEME: JSON.stringify(config.theme) } : {}),
114
115
  };
115
- return hostEnvFindings(checkHostEnv(emailHostEnv, candidate), null);
116
+ return hostEnvFindings(forWorker(checkHostEnv(emailHostEnv, candidate), workerDirectory), null);
117
+ }
118
+
119
+ /**
120
+ * **`pithy email provision` for the Worker this check ran for (#711).** It acts on one Worker, and in a project
121
+ * with several a bare one is refused `input/required`. Takes the Worker's `apps/` directory, which is what
122
+ * `--worker` takes and what that refusal lists. Not its `wrangler.jsonc` name: a scaffold deploys `apps/api` as
123
+ * `acme-api`.
124
+ */
125
+ function provisionCommand(workerDirectory: string): Command {
126
+ return pithyCommand("email provision", { flags: { "--worker": workerDirOf({ dir: workerDirectory }) } });
127
+ }
128
+
129
+ /**
130
+ * The host's own report, with its provisioning command named for this Worker by its `apps/` directory. The host
131
+ * writes the bare command into its log because it cannot know the Worker; a check that does know names it, in
132
+ * the action and the `fix` alike.
133
+ */
134
+ function forWorker(report: HostEnvReport<unknown>, workerDirectory: string): HostEnvReport<unknown> {
135
+ return {
136
+ ...report,
137
+ problems: report.problems.map((problem) =>
138
+ problem.provider.command === EMAIL_PROVISION
139
+ ? { ...problem, provider: { ...problem.provider, command: provisionCommand(workerDirectory) } }
140
+ : problem,
141
+ ),
142
+ };
116
143
  }
117
144
 
118
145
  /**
@@ -215,7 +242,8 @@ async function accountFindings(
215
242
  problem: `No D1 database named ${suppressions} exists on this account.`,
216
243
  // One database for the whole project, and one run creates it. `pithy email provision` spans every
217
244
  // declared environment and takes no `--env`, so naming one here was a flag the CLI refuses (#594).
218
- action: "Run `pithy email provision`. Nothing is suppressed until it exists.",
245
+ action: `Run \`${provisionCommand(context.workerDirectory)}\`. Nothing is suppressed until it exists.`,
246
+ fix: provisionCommand(context.workerDirectory),
219
247
  });
220
248
  }
221
249
 
@@ -245,6 +273,9 @@ async function accountFindings(
245
273
  * **What this sees:** a row under this registry name. A secret some other declaration moved off D1 has its
246
274
  * own check to write, or none; nothing here walks the vault for strays, because the vault cannot be listed.
247
275
  */
276
+ /** What creates a missing link-signing entry: a provision of every environment, production included (#711). */
277
+ const PROVISION_SECRETS = remedy("secrets provision");
278
+
248
279
  async function signingKeyFindings(context: SettingsAccountContext, environment: string): Promise<SettingsFinding[]> {
249
280
  const findings: SettingsFinding[] = [];
250
281
  const entry = environmentScope(context.project, environment).secretEntry(
@@ -256,8 +287,10 @@ async function signingKeyFindings(context: SettingsAccountContext, environment:
256
287
  setting: EMAIL_LINK_SIGNING_KEY,
257
288
  environment,
258
289
  problem: `The link-signing key has no Secrets Store entry in ${environment}, so no tracking or unsubscribe link can be signed.`,
259
- // No `--env`: the command spans every declared environment, and takes no such flag.
260
- action: "Run `pithy secrets provision`.",
290
+ // No `--env`: the command spans every declared environment, production included, and takes no such flag — so
291
+ // for one environment's entry it is a person's decision, never a `fix` (#711).
292
+ action: PROVISION_SECRETS.say((command) => `Run \`${command}\`.`),
293
+ ...(PROVISION_SECRETS.fix === undefined ? {} : { fix: PROVISION_SECRETS.fix }),
261
294
  });
262
295
  }
263
296
  if (await context.account.vaultSecret({ name: EMAIL_LINK_SIGNING_KEY, environment })) {
@@ -265,7 +298,9 @@ async function signingKeyFindings(context: SettingsAccountContext, environment:
265
298
  setting: EMAIL_LINK_SIGNING_KEY,
266
299
  environment,
267
300
  problem: `The link-signing key is still held in ${environment}'s D1 vault, where nothing reads it. Links signed with it before the move no longer verify.`,
268
- action: `Once the Secrets Store entry is bound and deployed, run \`pithy secrets rm ${EMAIL_LINK_SIGNING_KEY} --env ${environment} --backend d1\`. See docs/commands/secrets.md#moving-a-secret-off-d1.`,
301
+ action: `Once the Secrets Store entry is bound and deployed, the D1 copy can go: ${personDecision("secrets rm", { args: [EMAIL_LINK_SIGNING_KEY], flags: { "--env": environment, "--backend": "d1" } })} See docs/commands/secrets.md#moving-a-secret-off-d1.`,
302
+ // No `fix`: the removal is safe only once the entry is bound and deployed, which this check does not
303
+ // establish, so an agent running it as written could delete the only copy that still answers (#697).
269
304
  });
270
305
  }
271
306
  return findings;
@@ -274,7 +309,11 @@ async function signingKeyFindings(context: SettingsAccountContext, environment:
274
309
  /** Email's settings check, built from one composition's resolved config. Declared on the capability. */
275
310
  export function emailSettings(config: EmailSettingsInput): CapabilitySettings {
276
311
  return {
277
- local: (context) => [...localHostEnv(config), ...localForAddress(config), ...localBaseUrlOrigin(config, context)],
312
+ local: (context) => [
313
+ ...localHostEnv(config, context.workerDirectory),
314
+ ...localForAddress(config),
315
+ ...localBaseUrlOrigin(config, context),
316
+ ],
278
317
  account: (context) => accountFindings(config, context),
279
318
  };
280
319
  }
@@ -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.3.10";
16
+ export const PACKAGE_VERSION = "0.4.0";
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
4
  import type { D1Database } from "@cloudflare/workers-types";
5
+ import { pithyCommandOf, remedy } from "@pithy-sh/core/src/cli/command";
5
6
  import { defineHostEnv, type HostEnvProvider } from "@pithy-sh/core/src/workflow/hostEnv";
6
7
  import type { SecretBinding } from "@pithy-sh/secrets/src/env/bindings";
7
8
  import { z } from "zod";
@@ -46,14 +47,20 @@ import type { SendWorkflowInstances } from "./instances";
46
47
  *
47
48
  * No `--env`: it spans every declared environment in one run and declares no such flag, and a flag a
48
49
  * command does not declare is refused (#594) — so a remedy naming one is a remedy that cannot be followed.
50
+ *
51
+ * No `--worker` either, and only here: this is the sentence the deployed host writes into its own log, and
52
+ * a host does not know which app Worker's `apps/` directory provisioned it. `pithy doctor` reports the same
53
+ * finding for a Worker it knows, and names it there (`provision/settingsCheck.ts`, #711).
49
54
  */
50
- const PROVISION = "pithy email provision";
55
+ export const EMAIL_PROVISION = pithyCommandOf("email provision", {}, { runtime: true });
56
+ const PROVISION = EMAIL_PROVISION;
51
57
 
52
58
  /**
53
- * The command that writes both host secrets below. No `--env`, for the same reason: `pithy secrets provision`
54
- * provisions every declared environment in one run and declares no such flag.
59
+ * What writes both host secrets below, said as a person's decision. No `--env`, for the same reason: `pithy secrets
60
+ * provision` provisions every declared environment in one run, production included, and declares no such flag — so
61
+ * it is never a `Run` line for one host's secret (#711).
55
62
  */
56
- const SECRETS_PROVISION = "pithy secrets provision";
63
+ const SECRETS_PROVISION = remedy("secrets provision", {}, { runtime: true }).say((command) => command);
57
64
 
58
65
  /** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
59
66
  const binding = (name: string): HostEnvProvider => ({ kind: "binding", name, command: PROVISION });
@@ -210,12 +217,12 @@ export const emailHostEnv = defineHostEnv({
210
217
  SECRETS_ENCRYPTION_KEYS: {
211
218
  kind: "secret",
212
219
  name: "SECRETS_ENCRYPTION_KEYS",
213
- command: SECRETS_PROVISION,
220
+ decision: SECRETS_PROVISION,
214
221
  },
215
222
  [EMAIL_LINK_SIGNING_KEY_BINDING]: {
216
223
  kind: "secret",
217
224
  name: EMAIL_LINK_SIGNING_KEY,
218
- command: SECRETS_PROVISION,
225
+ decision: SECRETS_PROVISION,
219
226
  },
220
227
  EMAIL: binding("EMAIL"),
221
228
  EMAIL_SENDER: binding("EMAIL_SENDER"),