@pithy-sh/email 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/dist/analytics.d.ts +21 -0
  2. package/dist/analytics.d.ts.map +1 -0
  3. package/dist/analytics.js +15 -0
  4. package/dist/audit/actions.d.ts +47 -0
  5. package/dist/audit/actions.d.ts.map +1 -0
  6. package/dist/audit/actions.js +47 -0
  7. package/dist/bounce/classify.d.ts +40 -0
  8. package/dist/bounce/classify.d.ts.map +1 -0
  9. package/dist/bounce/classify.js +48 -0
  10. package/dist/bounce/handler.d.ts +34 -0
  11. package/dist/bounce/handler.d.ts.map +1 -0
  12. package/dist/bounce/handler.js +83 -0
  13. package/dist/capability.d.ts +160 -0
  14. package/dist/capability.d.ts.map +1 -0
  15. package/dist/capability.js +257 -0
  16. package/dist/crypto/signingKey.d.ts +38 -0
  17. package/dist/crypto/signingKey.d.ts.map +1 -0
  18. package/dist/crypto/signingKey.js +38 -0
  19. package/dist/crypto/token.d.ts +49 -0
  20. package/dist/crypto/token.d.ts.map +1 -0
  21. package/dist/crypto/token.js +101 -0
  22. package/dist/data/emailEvent.d.ts +30 -0
  23. package/dist/data/emailEvent.d.ts.map +1 -0
  24. package/dist/data/emailEvent.js +24 -0
  25. package/dist/data/emailJob.d.ts +78 -0
  26. package/dist/data/emailJob.d.ts.map +1 -0
  27. package/dist/data/emailJob.js +64 -0
  28. package/dist/data/emailSuppression.d.ts +25 -0
  29. package/dist/data/emailSuppression.d.ts.map +1 -0
  30. package/dist/data/emailSuppression.js +23 -0
  31. package/dist/data/enums.d.ts +78 -0
  32. package/dist/data/enums.d.ts.map +1 -0
  33. package/dist/data/enums.js +67 -0
  34. package/dist/data/tables.d.ts +116 -0
  35. package/dist/data/tables.d.ts.map +1 -0
  36. package/dist/data/tables.js +32 -0
  37. package/dist/error/errors.d.ts +62 -0
  38. package/dist/error/errors.d.ts.map +1 -0
  39. package/dist/error/errors.js +84 -0
  40. package/dist/http/callbacks.d.ts +23 -0
  41. package/dist/http/callbacks.d.ts.map +1 -0
  42. package/dist/http/callbacks.js +112 -0
  43. package/dist/http/guards.d.ts +101 -0
  44. package/dist/http/guards.d.ts.map +1 -0
  45. package/dist/http/guards.js +146 -0
  46. package/dist/http/responses.d.ts +297 -0
  47. package/dist/http/responses.d.ts.map +1 -0
  48. package/dist/http/responses.js +117 -0
  49. package/dist/http/routes.d.ts +73 -0
  50. package/dist/http/routes.d.ts.map +1 -0
  51. package/dist/http/routes.js +294 -0
  52. package/dist/http/schemas.d.ts +92 -0
  53. package/dist/http/schemas.d.ts.map +1 -0
  54. package/dist/http/schemas.js +93 -0
  55. package/dist/http/view.d.ts +80 -0
  56. package/dist/http/view.d.ts.map +1 -0
  57. package/dist/http/view.js +132 -0
  58. package/dist/index.d.ts +48 -0
  59. package/dist/index.d.ts.map +1 -0
  60. package/dist/index.js +13 -0
  61. package/dist/jobs/read.d.ts +193 -0
  62. package/dist/jobs/read.d.ts.map +1 -0
  63. package/dist/jobs/read.js +145 -0
  64. package/dist/jobs/retry.d.ts +101 -0
  65. package/dist/jobs/retry.d.ts.map +1 -0
  66. package/dist/jobs/retry.js +69 -0
  67. package/dist/migrations/0001_init.d.ts +34 -0
  68. package/dist/migrations/0001_init.d.ts.map +1 -0
  69. package/dist/migrations/0001_init.js +62 -0
  70. package/dist/migrations/0001_suppressions.d.ts +12 -0
  71. package/dist/migrations/0001_suppressions.d.ts.map +1 -0
  72. package/dist/migrations/0001_suppressions.js +22 -0
  73. package/dist/provision/devDelivery.d.ts +34 -0
  74. package/dist/provision/devDelivery.d.ts.map +1 -0
  75. package/dist/provision/devDelivery.js +39 -0
  76. package/dist/provision/hostCatalogs.d.ts +12 -0
  77. package/dist/provision/hostCatalogs.d.ts.map +1 -0
  78. package/dist/provision/hostCatalogs.js +80 -0
  79. package/dist/provision/provisionEmail.d.ts +145 -0
  80. package/dist/provision/provisionEmail.d.ts.map +1 -0
  81. package/dist/provision/provisionEmail.js +120 -0
  82. package/dist/provision/resolveEmailConfig.d.ts +124 -0
  83. package/dist/provision/resolveEmailConfig.d.ts.map +1 -0
  84. package/dist/provision/resolveEmailConfig.js +126 -0
  85. package/dist/provision/settingsCheck.d.ts +42 -0
  86. package/dist/provision/settingsCheck.d.ts.map +1 -0
  87. package/dist/provision/settingsCheck.js +140 -0
  88. package/dist/send/batchIdentity.d.ts +44 -0
  89. package/dist/send/batchIdentity.d.ts.map +1 -0
  90. package/dist/send/batchIdentity.js +48 -0
  91. package/dist/send/enqueue.d.ts +218 -0
  92. package/dist/send/enqueue.d.ts.map +1 -0
  93. package/dist/send/enqueue.js +155 -0
  94. package/dist/send/errorMapping.d.ts +29 -0
  95. package/dist/send/errorMapping.d.ts.map +1 -0
  96. package/dist/send/errorMapping.js +54 -0
  97. package/dist/send/events.d.ts +17 -0
  98. package/dist/send/events.d.ts.map +1 -0
  99. package/dist/send/events.js +19 -0
  100. package/dist/send/fromComposition.d.ts +49 -0
  101. package/dist/send/fromComposition.d.ts.map +1 -0
  102. package/dist/send/fromComposition.js +55 -0
  103. package/dist/send/retryPolicy.d.ts +34 -0
  104. package/dist/send/retryPolicy.d.ts.map +1 -0
  105. package/dist/send/retryPolicy.js +41 -0
  106. package/dist/send/runSend.d.ts +108 -0
  107. package/dist/send/runSend.d.ts.map +1 -0
  108. package/dist/send/runSend.js +220 -0
  109. package/dist/send/sendAt.d.ts +8 -0
  110. package/dist/send/sendAt.d.ts.map +1 -0
  111. package/dist/send/sendAt.js +64 -0
  112. package/dist/send/sender.d.ts +44 -0
  113. package/dist/send/sender.d.ts.map +1 -0
  114. package/dist/send/sender.js +2 -0
  115. package/dist/send/senderBinding.d.ts +46 -0
  116. package/dist/send/senderBinding.d.ts.map +1 -0
  117. package/dist/send/senderBinding.js +23 -0
  118. package/dist/send/suppression.d.ts +95 -0
  119. package/dist/send/suppression.d.ts.map +1 -0
  120. package/dist/send/suppression.js +134 -0
  121. package/dist/templates/engine.d.ts +111 -0
  122. package/dist/templates/engine.d.ts.map +1 -0
  123. package/dist/templates/engine.js +260 -0
  124. package/dist/templates/messages.d.ts +96 -0
  125. package/dist/templates/messages.d.ts.map +1 -0
  126. package/dist/templates/messages.es.d.ts +31 -0
  127. package/dist/templates/messages.es.d.ts.map +1 -0
  128. package/dist/templates/messages.es.js +84 -0
  129. package/dist/templates/messages.js +268 -0
  130. package/dist/templates/partials.d.ts +7 -0
  131. package/dist/templates/partials.d.ts.map +1 -0
  132. package/dist/templates/partials.js +61 -0
  133. package/dist/templates/precompiled.generated.d.ts +268 -0
  134. package/dist/templates/precompiled.generated.d.ts.map +1 -0
  135. package/dist/templates/precompiled.generated.js +4041 -0
  136. package/dist/templates/registry.d.ts +120 -0
  137. package/dist/templates/registry.d.ts.map +1 -0
  138. package/dist/templates/registry.js +325 -0
  139. package/dist/templates/samples.d.ts +9 -0
  140. package/dist/templates/samples.d.ts.map +1 -0
  141. package/dist/templates/samples.js +100 -0
  142. package/dist/templates/severity.d.ts +42 -0
  143. package/dist/templates/severity.d.ts.map +1 -0
  144. package/dist/templates/severity.js +83 -0
  145. package/dist/templates/theme.d.ts +195 -0
  146. package/dist/templates/theme.d.ts.map +1 -0
  147. package/dist/templates/theme.js +170 -0
  148. package/dist/version.generated.d.ts +7 -0
  149. package/dist/version.generated.d.ts.map +1 -0
  150. package/dist/version.generated.js +9 -0
  151. package/dist/workflows/hostApp.d.ts +35 -0
  152. package/dist/workflows/hostApp.d.ts.map +1 -0
  153. package/dist/workflows/hostApp.js +21 -0
  154. package/dist/workflows/hostEnv.d.ts +131 -0
  155. package/dist/workflows/hostEnv.d.ts.map +1 -0
  156. package/dist/workflows/hostEnv.js +149 -0
  157. package/dist/workflows/instanceLiveness.d.ts +5 -0
  158. package/dist/workflows/instanceLiveness.d.ts.map +1 -0
  159. package/dist/workflows/instanceLiveness.js +39 -0
  160. package/dist/workflows/instances.d.ts +20 -0
  161. package/dist/workflows/instances.d.ts.map +1 -0
  162. package/dist/workflows/instances.js +2 -0
  163. package/dist/workflows/params.d.ts +25 -0
  164. package/dist/workflows/params.d.ts.map +1 -0
  165. package/dist/workflows/params.js +23 -0
  166. package/dist/workflows/scheduler.d.ts +84 -0
  167. package/dist/workflows/scheduler.d.ts.map +1 -0
  168. package/dist/workflows/scheduler.js +113 -0
  169. package/dist/workflows/sendBatch.d.ts +87 -0
  170. package/dist/workflows/sendBatch.d.ts.map +1 -0
  171. package/dist/workflows/sendBatch.js +52 -0
  172. package/dist/workflows/worker.d.ts +102 -0
  173. package/dist/workflows/worker.d.ts.map +1 -0
  174. package/dist/workflows/worker.js +119 -0
  175. package/package.json +22 -11
  176. package/src/version.generated.ts +1 -1
@@ -0,0 +1,80 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { EMAIL_MESSAGES } from "../templates/messages.js";
4
+ import { KitErrorPayload } from "@pithy-sh/core/src/error/payload";
5
+ //#region src/provision/hostCatalogs.ts
6
+ /**
7
+ * The catalogs the prebuilt email host worker is deployed with — the provision-time half of
8
+ * `catalogLayers`.
9
+ *
10
+ * ## Why the host needs data where the app worker needs a seam
11
+ *
12
+ * An app worker composes capabilities, so `@pithy-sh/email`'s enqueue reaches a composed project's
13
+ * `layersFor` through the `compose` hook and renders a subject in whatever language the project
14
+ * speaks. The host worker composes nothing: `pithy email provision` deploys it from a committed
15
+ * template, and no `pithy.config.ts` of the adopter's is ever evaluated inside it. So the layers
16
+ * cannot travel as a function; they travel as one JSON var, and this is what flattens them.
17
+ *
18
+ * Nothing wrote that var before pithy-sh/pithy#441's remediation, which made the whole translated-body
19
+ * path dead in any real deployment: the send Workflow rendered the kit's English whatever tag was on
20
+ * the row, and — because `runSend` overwrites the stored subject with its own fresh render — discarded
21
+ * the translated subject the app worker had computed at enqueue as well. Two Workers, one message, and
22
+ * they disagreed about its language.
23
+ *
24
+ * ## What is dropped, and why dropping it changes nothing
25
+ *
26
+ * **Only `email/` keys.** The host renders email templates and nothing else, so a screen's copy or an
27
+ * error's translation in this var is weight against a hard 5 KB ceiling (see `resolveEmailConfig`) for
28
+ * a key no template will ever ask for.
29
+ *
30
+ * **And only keys that say something the host does not already have.** `catalogLayers` ends every
31
+ * lookup at `EMAIL_MESSAGES` — this package's own copy, in every language it is written in, bundled
32
+ * into the host — so a key whose merged value is byte-identical to what the host already resolves for
33
+ * that locale renders the same string whether it is in the var or not. Leaving it out is invisible in
34
+ * the rendered mail, and it is what makes adding a language cost no configuration at all: a project
35
+ * on the kit's own locales that overrode nothing deploys no catalog variable.
36
+ *
37
+ * An adopter who overrode a sentence is unaffected, including one who overrode a translation back to
38
+ * the English wording: the comparison is against the locale's own bundled value, which is not that.
39
+ */
40
+ /** The domain every key this capability renders lives under — `composeMessages` enforces it too. */
41
+ const EMAIL_KEY_PREFIX = "email/";
42
+ /**
43
+ * The `email/*` keys that are **error codes**, not template copy.
44
+ *
45
+ * The prefix alone is not the rule the doc below states. `email/send_failed` and its five siblings are
46
+ * catalog keys under this capability's domain because for an error the key *is* the code — but no
47
+ * template ever asks for one, and the host is the Worker that renders templates. A client translates
48
+ * an error from a catalog it already holds; the send Workflow never renders one.
49
+ *
50
+ * Worth the derivation rather than a list: it is 416 bytes of a 5120-byte ceiling that a real project
51
+ * already fills to 69%, so it is roughly 8% of the room a second locale would need. Read off
52
+ * `KitErrorPayload` so a seventh `email/*` code drops out on its own.
53
+ */
54
+ const EMAIL_ERROR_CODES = new Set(KitErrorPayload.options.map((member) => member.shape.code.value).filter((code) => code.startsWith(EMAIL_KEY_PREFIX)));
55
+ /** Whether a key is copy this host will actually render. */
56
+ function rendersOnTheHost(key) {
57
+ return key.startsWith(EMAIL_KEY_PREFIX) && !EMAIL_ERROR_CODES.has(key);
58
+ }
59
+ /**
60
+ * Flatten a composed project's layers into the `EMAIL_MESSAGES` var's value, one catalog per locale.
61
+ *
62
+ * `locales` is the project's `supportedLocales`; a project that composed no i18n capability passes
63
+ * none, gets `{}`, and deploys a host with no var at all — which is the same English it always sent.
64
+ */
65
+ function emailHostCatalogs(locales, layersFor) {
66
+ const catalogs = {};
67
+ for (const locale of locales) {
68
+ const merged = {};
69
+ for (const layer of [...layersFor(locale)].reverse()) for (const [key, value] of Object.entries(layer ?? {})) if (rendersOnTheHost(key)) merged[key] = value;
70
+ const bundled = {
71
+ ...EMAIL_MESSAGES.en ?? {},
72
+ ...EMAIL_MESSAGES[locale] ?? {}
73
+ };
74
+ for (const [key, value] of Object.entries(merged)) if (bundled[key] === value) delete merged[key];
75
+ if (Object.keys(merged).length > 0) catalogs[locale] = merged;
76
+ }
77
+ return catalogs;
78
+ }
79
+ //#endregion
80
+ export { emailHostCatalogs };
@@ -0,0 +1,145 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
4
+ import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
5
+ /**
6
+ * The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
7
+ * config wiring. It stands up the durable infrastructure the rest of the capability assumes: the
8
+ * suppression database (one per **project**, bound by every one of that project's environments) and the
9
+ * per-environment prebuilt email worker that hosts the send + scheduler Workflows and the every-minute
10
+ * cron.
11
+ *
12
+ * Unlike `@pithy-sh/secrets`, the email worker needs **no minted CF API token** — it sends through the
13
+ * Cloudflare Email Service `send_email` binding and reads its signing key through the `SECRETS` bindings,
14
+ * neither of which uses an API token. So provisioning here is purely: create + migrate the suppression
15
+ * DB, then deploy each environment's worker.
16
+ *
17
+ * The live Cloudflare/wrangler steps are behind the {@link EmailProvisioner} seam, so the orchestration
18
+ * (order, idempotency contract, per-env fan-out) is unit-tested without touching Cloudflare; the real
19
+ * seam implementation is the live-CF glue, exercised by the integration suite. Every step is idempotent —
20
+ * re-running provisioning is a no-op.
21
+ *
22
+ * **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
23
+ * onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
24
+ * app worker, and the link-signing key must exist (`pithy secrets create email-link-signing-key`). These
25
+ * are one-time account/DNS actions provisioning does not own.
26
+ */
27
+ /** The capability segment every email-owned name carries — the migration namespace and error domain too. */
28
+ export declare const EMAIL_CAPABILITY = "email";
29
+ /**
30
+ * The shared, durable suppression database — **one per project, shared across that project's
31
+ * environments**: `<project>-global-email-suppressions`.
32
+ *
33
+ * The sharing across environments is deliberate and load-bearing. "Do not email this person again" is
34
+ * not an environment-local fact; an address that hard-bounced in production must not be retried from
35
+ * staging, or the sending domain's reputation pays for the distinction. `global` sits in the
36
+ * environment slot to say so out loud rather than by omission.
37
+ *
38
+ * The sharing across **projects** was not deliberate — it was the absence of a project segment. D1's
39
+ * namespace is account-wide and provisioning reuses a database it finds by name, so a fixed
40
+ * `pithy-email-suppressions` meant a second, unrelated Pithy product in the same account silently
41
+ * inherited the first's opt-out list: one product's unsubscribe suppressing another product's
42
+ * transactional mail, with no row anywhere recording why. The project segment gives the scope a
43
+ * definition instead of an accident.
44
+ *
45
+ * Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
46
+ * a D1 database name's limit rather than the single 63 the generic composer defaults to.
47
+ */
48
+ export declare function suppressionDatabaseName(project: string): string;
49
+ /**
50
+ * The name of the inbound Email Routing rule that delivers bounce and complaint mail to the app worker.
51
+ *
52
+ * `global` in the environment slot because there is one rule per zone — the environments are separated
53
+ * by which app Worker the rule points at, not by the rule. Project-scoped and distinct from
54
+ * `@pithy-sh/support`'s `<project>-global-support-inbound`: `ensureWorkerRoute` keys idempotency on the
55
+ * rule *name*, so two projects sharing a zone under one unscoped name would each read the other's rule
56
+ * as their own, and one project's bounces would be delivered to the other's Worker.
57
+ *
58
+ * **The one name here still on the generic composer**, because an Email Routing rule is not a namespace
59
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for. The facade's whole point is
60
+ * that a kind of thing carries its own number; inventing one for this kind would be the opposite. So it
61
+ * takes the conservative default until that namespace lands.
62
+ */
63
+ export declare function bounceRoutingRuleName(project: string): string;
64
+ /**
65
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
66
+ * through core's naming facade under the **`worker`** namespace (63, the workers.dev cap), which
67
+ * `resolveEmailConfig` also stamps onto the config: one source, so the name the CLI audits and deletes
68
+ * under cannot drift from the name it deploys under. The environment is validated on the way through,
69
+ * so a stale `production` fails here rather than deploying a second host beside the real one.
70
+ */
71
+ export declare function emailWorkerName(project: string, env: ManagedEnvironment): string;
72
+ /** The live Cloudflare/wrangler seam. Each step must be idempotent. */
73
+ export interface EmailProvisioner {
74
+ /**
75
+ * Verify account prerequisites before any resource is created — most importantly a registered
76
+ * `workers.dev` subdomain, which Cloudflare requires to deploy the Workflow-hosting email worker.
77
+ * Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
78
+ */
79
+ preflight(): Promise<void>;
80
+ /** Create (or reuse) the project's suppression D1; returns its id. Idempotent. Runs once, before any env. */
81
+ ensureSuppressionDatabase(): Promise<{
82
+ databaseId: string;
83
+ }>;
84
+ /** Run the `email_0001_suppressions` migration against the suppression D1. Idempotent (applied ones skip). */
85
+ migrateSuppression(databaseId: string): Promise<void>;
86
+ /** Deploy the prebuilt email worker for this environment, wired to the suppression DB and the env's own resources. */
87
+ deployWorker(env: ManagedEnvironment, suppressionDatabaseId: string): Promise<void>;
88
+ /**
89
+ * Ensure the inbound Email Routing rule that points bounce/complaint mail at the production app worker
90
+ * (one per domain). Idempotent. Returns `skipped: true` when no routing config is supplied — the
91
+ * routing target and inbound address are an operator choice (and must not disturb the apex MX), so a
92
+ * project that hasn't decided yet provisions everything else and adds the rule later.
93
+ */
94
+ ensureRoutingRule(): Promise<{
95
+ created: boolean;
96
+ skipped: boolean;
97
+ }>;
98
+ }
99
+ /** What provisioning produced. */
100
+ export interface EmailProvisionResult {
101
+ suppressionDatabaseId: string;
102
+ environments: ManagedEnvironment[];
103
+ /** Whether the inbound routing rule was created, already present, or skipped (not configured). */
104
+ routing: {
105
+ created: boolean;
106
+ skipped: boolean;
107
+ };
108
+ }
109
+ /**
110
+ * Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
111
+ * email worker for every managed environment. The order matters — the suppression DB exists and is
112
+ * migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
113
+ *
114
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
115
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
116
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
117
+ */
118
+ export declare function provisionEmail(provisioner: EmailProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<EmailProvisionResult>;
119
+ /** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
120
+ export interface EmailDeprovisioner {
121
+ /** Delete the env's email worker. Idempotent (a missing worker is a no-op). */
122
+ deleteWorker(env: ManagedEnvironment): Promise<void>;
123
+ /**
124
+ * Delete the shared suppression D1. **Destructive** — the global suppression list is lost, so every
125
+ * environment forgets who unsubscribed or hard-bounced — so the orchestration only calls it when
126
+ * explicitly asked. Idempotent.
127
+ */
128
+ deleteSuppressionDatabase(): Promise<void>;
129
+ }
130
+ /** Teardown options. By default the suppression DB is **kept** — losing the global opt-out list is harmful. */
131
+ export interface EmailDeprovisionOptions {
132
+ /** Also delete the shared suppression database. Off by default; only a full destroy sets it. */
133
+ deleteSuppression?: boolean;
134
+ }
135
+ /**
136
+ * Tear down the email infrastructure, reversing {@link provisionEmail}: delete every environment's worker
137
+ * first (they bind the suppression DB), then — only when `deleteSuppression` is set — the shared
138
+ * suppression DB. The suppression list is preserved unless explicitly requested. Idempotent end to end.
139
+ *
140
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
141
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
142
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
143
+ */
144
+ export declare function deprovisionEmail(deprovisioner: EmailDeprovisioner, environments: DeclaredEnvironments | readonly string[], options?: EmailDeprovisionOptions): Promise<void>;
145
+ //# sourceMappingURL=provisionEmail.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"provisionEmail.d.ts","sourceRoot":"","sources":["../../src/provision/provisionEmail.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAIlF,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,6BAA6B,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;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;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAU/B;AAED,0HAA0H;AAC1H,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;OAIG;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;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,kBAAkB,EACjC,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,EACtD,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAKf"}
@@ -0,0 +1,120 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
4
+ import { resourceName } from "@pithy-sh/core/src/naming/resource";
5
+ import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
6
+ import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
7
+ //#region src/provision/provisionEmail.ts
8
+ /**
9
+ * The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
10
+ * config wiring. It stands up the durable infrastructure the rest of the capability assumes: the
11
+ * suppression database (one per **project**, bound by every one of that project's environments) and the
12
+ * per-environment prebuilt email worker that hosts the send + scheduler Workflows and the every-minute
13
+ * cron.
14
+ *
15
+ * Unlike `@pithy-sh/secrets`, the email worker needs **no minted CF API token** — it sends through the
16
+ * Cloudflare Email Service `send_email` binding and reads its signing key through the `SECRETS` bindings,
17
+ * neither of which uses an API token. So provisioning here is purely: create + migrate the suppression
18
+ * DB, then deploy each environment's worker.
19
+ *
20
+ * The live Cloudflare/wrangler steps are behind the {@link EmailProvisioner} seam, so the orchestration
21
+ * (order, idempotency contract, per-env fan-out) is unit-tested without touching Cloudflare; the real
22
+ * seam implementation is the live-CF glue, exercised by the integration suite. Every step is idempotent —
23
+ * re-running provisioning is a no-op.
24
+ *
25
+ * **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
26
+ * onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
27
+ * app worker, and the link-signing key must exist (`pithy secrets create email-link-signing-key`). These
28
+ * are one-time account/DNS actions provisioning does not own.
29
+ */
30
+ /** The capability segment every email-owned name carries — the migration namespace and error domain too. */
31
+ const EMAIL_CAPABILITY = "email";
32
+ /**
33
+ * The shared, durable suppression database — **one per project, shared across that project's
34
+ * environments**: `<project>-global-email-suppressions`.
35
+ *
36
+ * The sharing across environments is deliberate and load-bearing. "Do not email this person again" is
37
+ * not an environment-local fact; an address that hard-bounced in production must not be retried from
38
+ * staging, or the sending domain's reputation pays for the distinction. `global` sits in the
39
+ * environment slot to say so out loud rather than by omission.
40
+ *
41
+ * The sharing across **projects** was not deliberate — it was the absence of a project segment. D1's
42
+ * namespace is account-wide and provisioning reuses a database it finds by name, so a fixed
43
+ * `pithy-email-suppressions` meant a second, unrelated Pithy product in the same account silently
44
+ * inherited the first's opt-out list: one product's unsubscribe suppressing another product's
45
+ * transactional mail, with no row anywhere recording why. The project segment gives the scope a
46
+ * definition instead of an accident.
47
+ *
48
+ * Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
49
+ * a D1 database name's limit rather than the single 63 the generic composer defaults to.
50
+ */
51
+ function suppressionDatabaseName(project) {
52
+ return resourceNames(project).global.d1(`${EMAIL_CAPABILITY}-suppressions`);
53
+ }
54
+ /**
55
+ * The name of the inbound Email Routing rule that delivers bounce and complaint mail to the app worker.
56
+ *
57
+ * `global` in the environment slot because there is one rule per zone — the environments are separated
58
+ * by which app Worker the rule points at, not by the rule. Project-scoped and distinct from
59
+ * `@pithy-sh/support`'s `<project>-global-support-inbound`: `ensureWorkerRoute` keys idempotency on the
60
+ * rule *name*, so two projects sharing a zone under one unscoped name would each read the other's rule
61
+ * as their own, and one project's bounces would be delivered to the other's Worker.
62
+ *
63
+ * **The one name here still on the generic composer**, because an Email Routing rule is not a namespace
64
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for. The facade's whole point is
65
+ * that a kind of thing carries its own number; inventing one for this kind would be the opposite. So it
66
+ * takes the conservative default until that namespace lands.
67
+ */
68
+ function bounceRoutingRuleName(project) {
69
+ return resourceName({
70
+ project,
71
+ env: GLOBAL_SCOPE,
72
+ thing: `${EMAIL_CAPABILITY}-bounce`
73
+ });
74
+ }
75
+ /**
76
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
77
+ * through core's naming facade under the **`worker`** namespace (63, the workers.dev cap), which
78
+ * `resolveEmailConfig` also stamps onto the config: one source, so the name the CLI audits and deletes
79
+ * under cannot drift from the name it deploys under. The environment is validated on the way through,
80
+ * so a stale `production` fails here rather than deploying a second host beside the real one.
81
+ */
82
+ function emailWorkerName(project, env) {
83
+ return resourceNames(project).env(env).worker(EMAIL_CAPABILITY);
84
+ }
85
+ /**
86
+ * Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
87
+ * email worker for every managed environment. The order matters — the suppression DB exists and is
88
+ * migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
89
+ *
90
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
91
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
92
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
93
+ */
94
+ async function provisionEmail(provisioner, environments) {
95
+ await provisioner.preflight();
96
+ const { databaseId } = await provisioner.ensureSuppressionDatabase();
97
+ await provisioner.migrateSuppression(databaseId);
98
+ for (const env of managedEnvironments(environments)) await provisioner.deployWorker(env, databaseId);
99
+ const routing = await provisioner.ensureRoutingRule();
100
+ return {
101
+ suppressionDatabaseId: databaseId,
102
+ environments: managedEnvironments(environments),
103
+ routing
104
+ };
105
+ }
106
+ /**
107
+ * Tear down the email infrastructure, reversing {@link provisionEmail}: delete every environment's worker
108
+ * first (they bind the suppression DB), then — only when `deleteSuppression` is set — the shared
109
+ * suppression DB. The suppression list is preserved unless explicitly requested. Idempotent end to end.
110
+ *
111
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
112
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
113
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
114
+ */
115
+ async function deprovisionEmail(deprovisioner, environments, options = {}) {
116
+ for (const env of managedEnvironments(environments)) await deprovisioner.deleteWorker(env);
117
+ if (options.deleteSuppression) await deprovisioner.deleteSuppressionDatabase();
118
+ }
119
+ //#endregion
120
+ export { EMAIL_CAPABILITY, bounceRoutingRuleName, deprovisionEmail, emailWorkerName, provisionEmail, suppressionDatabaseName };
@@ -0,0 +1,124 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
4
+ import type { HostD1Binding, HostSecretsStoreBinding, HostSendEmailBinding, HostWorkflowBinding, WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
5
+ import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
6
+ import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
7
+ import type { EmailTheme } from "../templates/theme";
8
+ import { type DevMailDelivery } from "./devDelivery";
9
+ /**
10
+ * The email worker's `wrangler.jsonc` template shape. Email invented the prebuilt-host convention;
11
+ * `@pithy-sh/core`'s {@link WorkflowHostTemplate} is the generalization of it, so this is now that
12
+ * contract with the fields email's committed template always carries narrowed to required. The
13
+ * committed template (`src/workflows/wrangler.jsonc`) stays the source of truth for the static fields
14
+ * (compatibility date, the every-minute cron, class names, the `send_email` binding, theme vars).
15
+ */
16
+ export interface EmailWorkerWranglerTemplate extends WorkflowHostTemplate {
17
+ compatibility_date: string;
18
+ compatibility_flags: string[];
19
+ workers_dev: boolean;
20
+ d1_databases: HostD1Binding[];
21
+ send_email: HostSendEmailBinding[];
22
+ secrets_store_secrets: HostSecretsStoreBinding[];
23
+ workflows: HostWorkflowBinding[];
24
+ triggers: {
25
+ crons: string[];
26
+ };
27
+ vars: Record<string, string>;
28
+ }
29
+ /** The registry the host resolver derives its `workflows` array from, and the host's app dispatches on. */
30
+ export declare const emailWorkflowRegistry: WorkflowRegistry;
31
+ /**
32
+ * The most one Cloudflare Worker variable holds. **Per variable, and that is the whole design.**
33
+ *
34
+ * Cloudflare's documented limit is 5 KB per variable, on Free and Paid alike, and a Worker carries 64
35
+ * of them on Free and 128 on Paid. The failure it produces is API error 10054 at upload — a wrangler
36
+ * exit nobody can act on, in the middle of a provision run that has already created databases.
37
+ *
38
+ * So each locale travels in its own variable. One pack of the kit's Spanish is about 3 KB, which
39
+ * leaves 2 KB of room inside its own ceiling, and twenty languages is twenty variables rather than one
40
+ * 62 KB value that is refused outright. The host renders one email in one locale and never needs the
41
+ * other nineteen, so nothing is paid for the split.
42
+ *
43
+ * The check below therefore guards what it should: a single language pack growing past what a variable
44
+ * holds, which would take the kit's email copy growing by about two thirds. It is deliberately a
45
+ * refusal and not a truncation — a shortened catalog is a letter half in Spanish and half in English,
46
+ * with nothing anywhere failing to say so.
47
+ */
48
+ export declare const MAX_WORKER_VAR_BYTES: number;
49
+ /**
50
+ * One `EMAIL_MESSAGES_<LOCALE>` var per locale, or nothing when the project has no catalogs to carry.
51
+ *
52
+ * A locale with an empty catalog is omitted rather than written as `"{}"`: the host reads an absent
53
+ * variable as the kit's English, which is exactly what that means, and an empty object in the deployed
54
+ * config reads like a value somebody failed to fill.
55
+ *
56
+ * **Exported because this is not the only host that carries them.** `@pithy-sh/testers`' daily-pass
57
+ * worker reads the same variables through the same `catalogsFromEnv` seam, against the same ceiling —
58
+ * so the limit, the naming and the refusal are composed here once rather than restated there, where
59
+ * the second copy is the one that drifts.
60
+ */
61
+ export declare function emailMessagesVars(messages: LocaleCatalogs | undefined): Record<string, string>;
62
+ /** The resolved resource ids + per-env values for one environment's email-worker deploy. */
63
+ export interface EmailConfigParams {
64
+ /**
65
+ * The project name — the `<project>` segment the worker, both Workflows, and the suppression
66
+ * database name lead with. The root `pithy.config.ts` `name`, resolved by `requireProjectName` and
67
+ * never guessed: Worker script and Workflow names are account-scoped, so a wrong value here
68
+ * overwrites another project's running email host.
69
+ */
70
+ project: string;
71
+ /**
72
+ * The environment being resolved. `dev` as well as a deployed one: `pithy dev` resolves this same
73
+ * template into the local host config it runs, which is what {@link EmailConfigParams.devDelivery}
74
+ * governs.
75
+ */
76
+ env: ManagedEnvironment | "dev";
77
+ /** The app database id for this environment — where jobs/events live. */
78
+ appDatabaseId: string;
79
+ /** The shared suppression database id (same in every environment). */
80
+ suppressionDatabaseId: string;
81
+ /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the signing key. */
82
+ secretsDatabaseId: string;
83
+ /** The CF Secrets Store id holding the per-env master key. */
84
+ storeId: string;
85
+ /** The app worker's public base URL for this environment — callback links are built against it. */
86
+ baseUrl: string;
87
+ /** The resolved brand theme — serialized into the worker's `EMAIL_THEME` var. */
88
+ theme: EmailTheme;
89
+ /**
90
+ * This project's email catalogs — serialized into the worker's `EMAIL_MESSAGES` var.
91
+ *
92
+ * The same journey `theme` makes, and for the same reason: the host composes no capabilities, so
93
+ * anything the adopter configured has to arrive as data. `emailHostCatalogs` builds it from the
94
+ * composed project's layers; a project that composed no i18n capability passes `{}` or omits it, and
95
+ * the var is not written at all.
96
+ */
97
+ messages?: LocaleCatalogs;
98
+ /**
99
+ * What the host's `send_email` binding does under `pithy dev` — the adopter's `email({ devDelivery })`.
100
+ * Defaults to `remote`, which sends real mail from the developer's machine. Ignored outside `dev`.
101
+ */
102
+ devDelivery?: DevMailDelivery;
103
+ }
104
+ /**
105
+ * Resolve the email-worker `wrangler.jsonc` template into one environment's standalone config — no
106
+ * `[env.*]` stanzas (staging and prod are genuinely separate workers, per CLAUDE.md).
107
+ *
108
+ * The mechanics are `@pithy-sh/core`'s {@link resolveWorkflowHost}: this is the email-shaped face of
109
+ * it, mapping email's seven inputs onto the generic host params. What stays here is the part that is
110
+ * genuinely email's — which binding takes which database id, and the `@pithy-sh/secrets` import that
111
+ * names the env-scoped master key. Core must never depend on `@pithy-sh/secrets`, so the resolved
112
+ * string is passed in rather than the naming rule being hoisted.
113
+ *
114
+ * `send_email`'s `remote` flag is the one thing here that is a *decision* rather than a fill: real
115
+ * delivery is the default in every environment, and `dev` alone may choose the local simulator
116
+ * instead (`devDelivery.ts`).
117
+ *
118
+ * Only `EMAIL_SUPPRESSIONS`'s `database_name` is rewritten. That database is email's own, and its name
119
+ * now carries the project — leaving the template's `pithy-email-suppressions` in place would print a
120
+ * name no account holds. `pithy-app` and `pithy-secrets` are owned elsewhere and pass through
121
+ * untouched; only their ids differ per environment.
122
+ */
123
+ export declare function resolveEmailConfig(template: EmailWorkerWranglerTemplate, params: EmailConfigParams): EmailWorkerWranglerTemplate;
124
+ //# sourceMappingURL=resolveEmailConfig.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolveEmailConfig.d.ts","sourceRoot":"","sources":["../../src/provision/resolveEmailConfig.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAE,KAAK,eAAe,EAAuB,MAAM,eAAe,CAAC;AAG1E;;;;;;GAMG;AACH,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACvE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,qBAAqB,EAAE,uBAAuB,EAAE,CAAC;IACjD,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AA4BD,2GAA2G;AAC3G,eAAO,MAAM,qBAAqB,EAAE,gBAKnC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,QAAW,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiB9F;AAED,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,GAAG,EAAE,kBAAkB,GAAG,KAAK,CAAC;IAChC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kGAAkG;IAClG,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAK/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,2BAA2B,EACrC,MAAM,EAAE,iBAAiB,GACxB,2BAA2B,CA6B7B"}
@@ -0,0 +1,126 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { emailCatalogVarName } from "../templates/messages.js";
4
+ import { emailRemoteBindings } from "./devDelivery.js";
5
+ import { EMAIL_CAPABILITY, suppressionDatabaseName } from "./provisionEmail.js";
6
+ import { EmailScheduleParams, EmailSendParams } from "../workflows/params.js";
7
+ import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
8
+ import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
9
+ import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
10
+ import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
11
+ /** The registry the host resolver derives its `workflows` array from, and the host's app dispatches on. */
12
+ const emailWorkflowRegistry = Object.fromEntries(Object.entries({
13
+ send: {
14
+ binding: "EMAIL_SENDER",
15
+ className: "EmailSendWorkflow",
16
+ params: EmailSendParams
17
+ },
18
+ schedule: {
19
+ binding: "EMAIL_SCHEDULER",
20
+ className: "EmailSchedulerWorkflow",
21
+ params: EmailScheduleParams,
22
+ schedule: "* * * * *"
23
+ }
24
+ }).map(([job, spec]) => {
25
+ const key = workflowKey(EMAIL_CAPABILITY, job);
26
+ return [key, {
27
+ key,
28
+ capability: EMAIL_CAPABILITY,
29
+ job,
30
+ spec
31
+ }];
32
+ }));
33
+ /**
34
+ * The most one Cloudflare Worker variable holds. **Per variable, and that is the whole design.**
35
+ *
36
+ * Cloudflare's documented limit is 5 KB per variable, on Free and Paid alike, and a Worker carries 64
37
+ * of them on Free and 128 on Paid. The failure it produces is API error 10054 at upload — a wrangler
38
+ * exit nobody can act on, in the middle of a provision run that has already created databases.
39
+ *
40
+ * So each locale travels in its own variable. One pack of the kit's Spanish is about 3 KB, which
41
+ * leaves 2 KB of room inside its own ceiling, and twenty languages is twenty variables rather than one
42
+ * 62 KB value that is refused outright. The host renders one email in one locale and never needs the
43
+ * other nineteen, so nothing is paid for the split.
44
+ *
45
+ * The check below therefore guards what it should: a single language pack growing past what a variable
46
+ * holds, which would take the kit's email copy growing by about two thirds. It is deliberately a
47
+ * refusal and not a truncation — a shortened catalog is a letter half in Spanish and half in English,
48
+ * with nothing anywhere failing to say so.
49
+ */
50
+ const MAX_WORKER_VAR_BYTES = 5120;
51
+ /**
52
+ * One `EMAIL_MESSAGES_<LOCALE>` var per locale, or nothing when the project has no catalogs to carry.
53
+ *
54
+ * A locale with an empty catalog is omitted rather than written as `"{}"`: the host reads an absent
55
+ * variable as the kit's English, which is exactly what that means, and an empty object in the deployed
56
+ * config reads like a value somebody failed to fill.
57
+ *
58
+ * **Exported because this is not the only host that carries them.** `@pithy-sh/testers`' daily-pass
59
+ * worker reads the same variables through the same `catalogsFromEnv` seam, against the same ceiling —
60
+ * so the limit, the naming and the refusal are composed here once rather than restated there, where
61
+ * the second copy is the one that drifts.
62
+ */
63
+ function emailMessagesVars(messages) {
64
+ if (!messages) return {};
65
+ const vars = {};
66
+ for (const [locale, catalog] of Object.entries(messages)) {
67
+ if (!catalog || Object.keys(catalog).length === 0) continue;
68
+ const serialized = JSON.stringify(catalog);
69
+ const bytes = new TextEncoder().encode(serialized).length;
70
+ if (bytes > 5120) throw new ValidationError({
71
+ message: `The \`${locale}\` email catalog is ${bytes} bytes; a Cloudflare Worker variable holds ${MAX_WORKER_VAR_BYTES}.`,
72
+ action: `Shorten the \`email/\` sentences for \`${locale}\` in i18n({ messages }), or drop that locale from supportedLocales.`,
73
+ detail: `${emailCatalogVarName(locale)} serialized to ${bytes} bytes over the ${MAX_WORKER_VAR_BYTES}-byte limit; Cloudflare refuses the upload with error 10054.`
74
+ });
75
+ vars[emailCatalogVarName(locale)] = serialized;
76
+ }
77
+ return vars;
78
+ }
79
+ /**
80
+ * Resolve the email-worker `wrangler.jsonc` template into one environment's standalone config — no
81
+ * `[env.*]` stanzas (staging and prod are genuinely separate workers, per CLAUDE.md).
82
+ *
83
+ * The mechanics are `@pithy-sh/core`'s {@link resolveWorkflowHost}: this is the email-shaped face of
84
+ * it, mapping email's seven inputs onto the generic host params. What stays here is the part that is
85
+ * genuinely email's — which binding takes which database id, and the `@pithy-sh/secrets` import that
86
+ * names the env-scoped master key. Core must never depend on `@pithy-sh/secrets`, so the resolved
87
+ * string is passed in rather than the naming rule being hoisted.
88
+ *
89
+ * `send_email`'s `remote` flag is the one thing here that is a *decision* rather than a fill: real
90
+ * delivery is the default in every environment, and `dev` alone may choose the local simulator
91
+ * instead (`devDelivery.ts`).
92
+ *
93
+ * Only `EMAIL_SUPPRESSIONS`'s `database_name` is rewritten. That database is email's own, and its name
94
+ * now carries the project — leaving the template's `pithy-email-suppressions` in place would print a
95
+ * name no account holds. `pithy-app` and `pithy-secrets` are owned elsewhere and pass through
96
+ * untouched; only their ids differ per environment.
97
+ */
98
+ function resolveEmailConfig(template, params) {
99
+ const { project, env, appDatabaseId, suppressionDatabaseId, secretsDatabaseId, storeId, baseUrl, theme } = params;
100
+ return resolveWorkflowHost(template, {
101
+ project,
102
+ capability: EMAIL_CAPABILITY,
103
+ env,
104
+ databaseIds: {
105
+ DB: appDatabaseId,
106
+ EMAIL_SUPPRESSIONS: suppressionDatabaseId,
107
+ SECRETS: secretsDatabaseId
108
+ },
109
+ databaseNames: { EMAIL_SUPPRESSIONS: suppressionDatabaseName(project) },
110
+ secretsStoreId: storeId,
111
+ masterKeySecretName: masterKeySecretName(project, env),
112
+ vars: {
113
+ EMAIL_THEME: JSON.stringify(theme),
114
+ BASE_URL: baseUrl,
115
+ ...emailMessagesVars(params.messages)
116
+ },
117
+ remoteBindings: emailRemoteBindings(env, params.devDelivery ?? "remote"),
118
+ workflows: hostWorkflowsFor(emailWorkflowRegistry, {
119
+ project,
120
+ capability: EMAIL_CAPABILITY,
121
+ env
122
+ }).workflows
123
+ });
124
+ }
125
+ //#endregion
126
+ export { MAX_WORKER_VAR_BYTES, emailMessagesVars, emailWorkflowRegistry, resolveEmailConfig };
@@ -0,0 +1,42 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { CapabilitySettings } from "@pithy-sh/core/src/capability/settings";
4
+ import type { EmailTheme } from "../templates/theme";
5
+ /**
6
+ * Whether email's settings **work**, as `pithy doctor` asks it (pithy-sh/pithy#411).
7
+ *
8
+ * Every check doctor had before this one asked about presence: the `email({ … })` option keys are
9
+ * written, the `DB` and `EMAIL_SENDER` bindings are declared, the ledger is level. All of them pass while
10
+ * `fromAddress` names a domain nobody onboarded, the link-signing key was never created, `BASE_URL` is
11
+ * staging's URL in production's config, and the suppression database does not exist — and the way an
12
+ * adopter learns any of that is a message that never arrives.
13
+ *
14
+ * ## The local tier runs the host's own schema
15
+ *
16
+ * `checkHostEnv(emailHostEnv, …)` is not a second reading of the same rules — it is *the* reading. The
17
+ * prebuilt host worker refuses to start on the same declaration (`workflows/worker.ts`), so a value doctor
18
+ * calls good is a value the host will accept, and a rule that changes changes in one file. Bindings are
19
+ * stubbed on the way in, deliberately: whether `DB` is bound is `pithy doctor`'s `bindings` check and
20
+ * `Secret bindings:` block, and asking it twice would report one fault as two.
21
+ *
22
+ * ## The account tier asks the three things only the account knows
23
+ *
24
+ * Is the sending domain a zone here, does the suppression database exist, does the signing key have a
25
+ * value. Each costs one Cloudflare call, each is skipped whole when the account cannot be reached, and
26
+ * none of them is inferable from a file in the checkout.
27
+ *
28
+ * Nothing here writes. Every finding names the command, the config key, or the one-time dashboard action
29
+ * that resolves it.
30
+ */
31
+ /** The resolved config slice the check reads. The capability builds it; nothing here parses config. */
32
+ export interface EmailSettingsInput {
33
+ /** The address every message is sent from — its domain is what must be onboarded. */
34
+ fromAddress: string;
35
+ /** The public base URL every link in a message is built against. */
36
+ baseUrl: string;
37
+ /** The resolved theme, as the host receives it: one JSON var. */
38
+ theme?: EmailTheme;
39
+ }
40
+ /** Email's settings check, built from one composition's resolved config. Declared on the capability. */
41
+ export declare function emailSettings(config: EmailSettingsInput): CapabilitySettings;
42
+ //# sourceMappingURL=settingsCheck.d.ts.map