@pithy-sh/email 0.1.2 → 0.1.3

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 +19 -0
  2. package/dist/analytics.d.ts.map +1 -0
  3. package/dist/analytics.js +13 -0
  4. package/dist/audit/actions.d.ts +45 -0
  5. package/dist/audit/actions.d.ts.map +1 -0
  6. package/dist/audit/actions.js +45 -0
  7. package/dist/bounce/classify.d.ts +38 -0
  8. package/dist/bounce/classify.d.ts.map +1 -0
  9. package/dist/bounce/classify.js +46 -0
  10. package/dist/bounce/handler.d.ts +32 -0
  11. package/dist/bounce/handler.d.ts.map +1 -0
  12. package/dist/bounce/handler.js +81 -0
  13. package/dist/capability.d.ts +158 -0
  14. package/dist/capability.d.ts.map +1 -0
  15. package/dist/capability.js +255 -0
  16. package/dist/crypto/signingKey.d.ts +36 -0
  17. package/dist/crypto/signingKey.d.ts.map +1 -0
  18. package/dist/crypto/signingKey.js +36 -0
  19. package/dist/crypto/token.d.ts +47 -0
  20. package/dist/crypto/token.d.ts.map +1 -0
  21. package/dist/crypto/token.js +99 -0
  22. package/dist/data/emailEvent.d.ts +28 -0
  23. package/dist/data/emailEvent.d.ts.map +1 -0
  24. package/dist/data/emailEvent.js +22 -0
  25. package/dist/data/emailJob.d.ts +76 -0
  26. package/dist/data/emailJob.d.ts.map +1 -0
  27. package/dist/data/emailJob.js +62 -0
  28. package/dist/data/emailSuppression.d.ts +23 -0
  29. package/dist/data/emailSuppression.d.ts.map +1 -0
  30. package/dist/data/emailSuppression.js +21 -0
  31. package/dist/data/enums.d.ts +76 -0
  32. package/dist/data/enums.d.ts.map +1 -0
  33. package/dist/data/enums.js +65 -0
  34. package/dist/data/tables.d.ts +114 -0
  35. package/dist/data/tables.d.ts.map +1 -0
  36. package/dist/data/tables.js +30 -0
  37. package/dist/error/errors.d.ts +60 -0
  38. package/dist/error/errors.d.ts.map +1 -0
  39. package/dist/error/errors.js +82 -0
  40. package/dist/http/callbacks.d.ts +21 -0
  41. package/dist/http/callbacks.d.ts.map +1 -0
  42. package/dist/http/callbacks.js +110 -0
  43. package/dist/http/guards.d.ts +99 -0
  44. package/dist/http/guards.d.ts.map +1 -0
  45. package/dist/http/guards.js +144 -0
  46. package/dist/http/responses.d.ts +295 -0
  47. package/dist/http/responses.d.ts.map +1 -0
  48. package/dist/http/responses.js +115 -0
  49. package/dist/http/routes.d.ts +71 -0
  50. package/dist/http/routes.d.ts.map +1 -0
  51. package/dist/http/routes.js +292 -0
  52. package/dist/http/schemas.d.ts +90 -0
  53. package/dist/http/schemas.d.ts.map +1 -0
  54. package/dist/http/schemas.js +91 -0
  55. package/dist/http/view.d.ts +78 -0
  56. package/dist/http/view.d.ts.map +1 -0
  57. package/dist/http/view.js +130 -0
  58. package/dist/index.d.ts +46 -0
  59. package/dist/index.d.ts.map +1 -0
  60. package/dist/index.js +11 -0
  61. package/dist/jobs/read.d.ts +191 -0
  62. package/dist/jobs/read.d.ts.map +1 -0
  63. package/dist/jobs/read.js +143 -0
  64. package/dist/jobs/retry.d.ts +99 -0
  65. package/dist/jobs/retry.d.ts.map +1 -0
  66. package/dist/jobs/retry.js +67 -0
  67. package/dist/migrations/0001_init.d.ts +32 -0
  68. package/dist/migrations/0001_init.d.ts.map +1 -0
  69. package/dist/migrations/0001_init.js +60 -0
  70. package/dist/migrations/0001_suppressions.d.ts +10 -0
  71. package/dist/migrations/0001_suppressions.d.ts.map +1 -0
  72. package/dist/migrations/0001_suppressions.js +20 -0
  73. package/dist/provision/devDelivery.d.ts +32 -0
  74. package/dist/provision/devDelivery.d.ts.map +1 -0
  75. package/dist/provision/devDelivery.js +37 -0
  76. package/dist/provision/hostCatalogs.d.ts +10 -0
  77. package/dist/provision/hostCatalogs.d.ts.map +1 -0
  78. package/dist/provision/hostCatalogs.js +78 -0
  79. package/dist/provision/provisionEmail.d.ts +143 -0
  80. package/dist/provision/provisionEmail.d.ts.map +1 -0
  81. package/dist/provision/provisionEmail.js +118 -0
  82. package/dist/provision/resolveEmailConfig.d.ts +122 -0
  83. package/dist/provision/resolveEmailConfig.d.ts.map +1 -0
  84. package/dist/provision/resolveEmailConfig.js +124 -0
  85. package/dist/provision/settingsCheck.d.ts +40 -0
  86. package/dist/provision/settingsCheck.d.ts.map +1 -0
  87. package/dist/provision/settingsCheck.js +138 -0
  88. package/dist/send/batchIdentity.d.ts +42 -0
  89. package/dist/send/batchIdentity.d.ts.map +1 -0
  90. package/dist/send/batchIdentity.js +46 -0
  91. package/dist/send/enqueue.d.ts +216 -0
  92. package/dist/send/enqueue.d.ts.map +1 -0
  93. package/dist/send/enqueue.js +153 -0
  94. package/dist/send/errorMapping.d.ts +27 -0
  95. package/dist/send/errorMapping.d.ts.map +1 -0
  96. package/dist/send/errorMapping.js +52 -0
  97. package/dist/send/events.d.ts +15 -0
  98. package/dist/send/events.d.ts.map +1 -0
  99. package/dist/send/events.js +17 -0
  100. package/dist/send/fromComposition.d.ts +47 -0
  101. package/dist/send/fromComposition.d.ts.map +1 -0
  102. package/dist/send/fromComposition.js +53 -0
  103. package/dist/send/retryPolicy.d.ts +32 -0
  104. package/dist/send/retryPolicy.d.ts.map +1 -0
  105. package/dist/send/retryPolicy.js +39 -0
  106. package/dist/send/runSend.d.ts +106 -0
  107. package/dist/send/runSend.d.ts.map +1 -0
  108. package/dist/send/runSend.js +218 -0
  109. package/dist/send/sendAt.d.ts +6 -0
  110. package/dist/send/sendAt.d.ts.map +1 -0
  111. package/dist/send/sendAt.js +62 -0
  112. package/dist/send/sender.d.ts +42 -0
  113. package/dist/send/sender.d.ts.map +1 -0
  114. package/dist/send/sender.js +0 -0
  115. package/dist/send/senderBinding.d.ts +44 -0
  116. package/dist/send/senderBinding.d.ts.map +1 -0
  117. package/dist/send/senderBinding.js +21 -0
  118. package/dist/send/suppression.d.ts +93 -0
  119. package/dist/send/suppression.d.ts.map +1 -0
  120. package/dist/send/suppression.js +132 -0
  121. package/dist/templates/engine.d.ts +109 -0
  122. package/dist/templates/engine.d.ts.map +1 -0
  123. package/dist/templates/engine.js +258 -0
  124. package/dist/templates/messages.d.ts +94 -0
  125. package/dist/templates/messages.d.ts.map +1 -0
  126. package/dist/templates/messages.es.d.ts +29 -0
  127. package/dist/templates/messages.es.d.ts.map +1 -0
  128. package/dist/templates/messages.es.js +82 -0
  129. package/dist/templates/messages.js +266 -0
  130. package/dist/templates/partials.d.ts +5 -0
  131. package/dist/templates/partials.d.ts.map +1 -0
  132. package/dist/templates/partials.js +59 -0
  133. package/dist/templates/precompiled.generated.d.ts +266 -0
  134. package/dist/templates/precompiled.generated.d.ts.map +1 -0
  135. package/dist/templates/precompiled.generated.js +4039 -0
  136. package/dist/templates/registry.d.ts +118 -0
  137. package/dist/templates/registry.d.ts.map +1 -0
  138. package/dist/templates/registry.js +323 -0
  139. package/dist/templates/samples.d.ts +7 -0
  140. package/dist/templates/samples.d.ts.map +1 -0
  141. package/dist/templates/samples.js +98 -0
  142. package/dist/templates/severity.d.ts +40 -0
  143. package/dist/templates/severity.d.ts.map +1 -0
  144. package/dist/templates/severity.js +81 -0
  145. package/dist/templates/theme.d.ts +193 -0
  146. package/dist/templates/theme.d.ts.map +1 -0
  147. package/dist/templates/theme.js +168 -0
  148. package/dist/version.generated.d.ts +5 -0
  149. package/dist/version.generated.d.ts.map +1 -0
  150. package/dist/version.generated.js +7 -0
  151. package/dist/workflows/hostApp.d.ts +33 -0
  152. package/dist/workflows/hostApp.d.ts.map +1 -0
  153. package/dist/workflows/hostApp.js +19 -0
  154. package/dist/workflows/hostEnv.d.ts +129 -0
  155. package/dist/workflows/hostEnv.d.ts.map +1 -0
  156. package/dist/workflows/hostEnv.js +147 -0
  157. package/dist/workflows/instanceLiveness.d.ts +3 -0
  158. package/dist/workflows/instanceLiveness.d.ts.map +1 -0
  159. package/dist/workflows/instanceLiveness.js +37 -0
  160. package/dist/workflows/instances.d.ts +18 -0
  161. package/dist/workflows/instances.d.ts.map +1 -0
  162. package/dist/workflows/instances.js +0 -0
  163. package/dist/workflows/params.d.ts +23 -0
  164. package/dist/workflows/params.d.ts.map +1 -0
  165. package/dist/workflows/params.js +21 -0
  166. package/dist/workflows/scheduler.d.ts +82 -0
  167. package/dist/workflows/scheduler.d.ts.map +1 -0
  168. package/dist/workflows/scheduler.js +111 -0
  169. package/dist/workflows/sendBatch.d.ts +85 -0
  170. package/dist/workflows/sendBatch.d.ts.map +1 -0
  171. package/dist/workflows/sendBatch.js +50 -0
  172. package/dist/workflows/worker.d.ts +100 -0
  173. package/dist/workflows/worker.d.ts.map +1 -0
  174. package/dist/workflows/worker.js +117 -0
  175. package/package.json +22 -11
  176. package/src/version.generated.ts +1 -1
@@ -0,0 +1,143 @@
1
+ import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
2
+ import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
3
+ /**
4
+ * The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
5
+ * config wiring. It stands up the durable infrastructure the rest of the capability assumes: the
6
+ * suppression database (one per **project**, bound by every one of that project's environments) and the
7
+ * per-environment prebuilt email worker that hosts the send + scheduler Workflows and the every-minute
8
+ * cron.
9
+ *
10
+ * Unlike `@pithy-sh/secrets`, the email worker needs **no minted CF API token** — it sends through the
11
+ * Cloudflare Email Service `send_email` binding and reads its signing key through the `SECRETS` bindings,
12
+ * neither of which uses an API token. So provisioning here is purely: create + migrate the suppression
13
+ * DB, then deploy each environment's worker.
14
+ *
15
+ * The live Cloudflare/wrangler steps are behind the {@link EmailProvisioner} seam, so the orchestration
16
+ * (order, idempotency contract, per-env fan-out) is unit-tested without touching Cloudflare; the real
17
+ * seam implementation is the live-CF glue, exercised by the integration suite. Every step is idempotent —
18
+ * re-running provisioning is a no-op.
19
+ *
20
+ * **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
21
+ * onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
22
+ * app worker, and the link-signing key must exist (`pithy secrets create email-link-signing-key`). These
23
+ * are one-time account/DNS actions provisioning does not own.
24
+ */
25
+ /** The capability segment every email-owned name carries — the migration namespace and error domain too. */
26
+ export declare const EMAIL_CAPABILITY = "email";
27
+ /**
28
+ * The shared, durable suppression database — **one per project, shared across that project's
29
+ * environments**: `<project>-global-email-suppressions`.
30
+ *
31
+ * The sharing across environments is deliberate and load-bearing. "Do not email this person again" is
32
+ * not an environment-local fact; an address that hard-bounced in production must not be retried from
33
+ * staging, or the sending domain's reputation pays for the distinction. `global` sits in the
34
+ * environment slot to say so out loud rather than by omission.
35
+ *
36
+ * The sharing across **projects** was not deliberate — it was the absence of a project segment. D1's
37
+ * namespace is account-wide and provisioning reuses a database it finds by name, so a fixed
38
+ * `pithy-email-suppressions` meant a second, unrelated Pithy product in the same account silently
39
+ * inherited the first's opt-out list: one product's unsubscribe suppressing another product's
40
+ * transactional mail, with no row anywhere recording why. The project segment gives the scope a
41
+ * definition instead of an accident.
42
+ *
43
+ * Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
44
+ * a D1 database name's limit rather than the single 63 the generic composer defaults to.
45
+ */
46
+ export declare function suppressionDatabaseName(project: string): string;
47
+ /**
48
+ * The name of the inbound Email Routing rule that delivers bounce and complaint mail to the app worker.
49
+ *
50
+ * `global` in the environment slot because there is one rule per zone — the environments are separated
51
+ * by which app Worker the rule points at, not by the rule. Project-scoped and distinct from
52
+ * `@pithy-sh/support`'s `<project>-global-support-inbound`: `ensureWorkerRoute` keys idempotency on the
53
+ * rule *name*, so two projects sharing a zone under one unscoped name would each read the other's rule
54
+ * as their own, and one project's bounces would be delivered to the other's Worker.
55
+ *
56
+ * **The one name here still on the generic composer**, because an Email Routing rule is not a namespace
57
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for. The facade's whole point is
58
+ * that a kind of thing carries its own number; inventing one for this kind would be the opposite. So it
59
+ * takes the conservative default until that namespace lands.
60
+ */
61
+ export declare function bounceRoutingRuleName(project: string): string;
62
+ /**
63
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
64
+ * through core's naming facade under the **`worker`** namespace (63, the workers.dev cap), which
65
+ * `resolveEmailConfig` also stamps onto the config: one source, so the name the CLI audits and deletes
66
+ * under cannot drift from the name it deploys under. The environment is validated on the way through,
67
+ * so a stale `production` fails here rather than deploying a second host beside the real one.
68
+ */
69
+ export declare function emailWorkerName(project: string, env: ManagedEnvironment): string;
70
+ /** The live Cloudflare/wrangler seam. Each step must be idempotent. */
71
+ export interface EmailProvisioner {
72
+ /**
73
+ * Verify account prerequisites before any resource is created — most importantly a registered
74
+ * `workers.dev` subdomain, which Cloudflare requires to deploy the Workflow-hosting email worker.
75
+ * Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
76
+ */
77
+ preflight(): Promise<void>;
78
+ /** Create (or reuse) the project's suppression D1; returns its id. Idempotent. Runs once, before any env. */
79
+ ensureSuppressionDatabase(): Promise<{
80
+ databaseId: string;
81
+ }>;
82
+ /** Run the `email_0001_suppressions` migration against the suppression D1. Idempotent (applied ones skip). */
83
+ migrateSuppression(databaseId: string): Promise<void>;
84
+ /** Deploy the prebuilt email worker for this environment, wired to the suppression DB and the env's own resources. */
85
+ deployWorker(env: ManagedEnvironment, suppressionDatabaseId: string): Promise<void>;
86
+ /**
87
+ * Ensure the inbound Email Routing rule that points bounce/complaint mail at the production app worker
88
+ * (one per domain). Idempotent. Returns `skipped: true` when no routing config is supplied — the
89
+ * routing target and inbound address are an operator choice (and must not disturb the apex MX), so a
90
+ * project that hasn't decided yet provisions everything else and adds the rule later.
91
+ */
92
+ ensureRoutingRule(): Promise<{
93
+ created: boolean;
94
+ skipped: boolean;
95
+ }>;
96
+ }
97
+ /** What provisioning produced. */
98
+ export interface EmailProvisionResult {
99
+ suppressionDatabaseId: string;
100
+ environments: ManagedEnvironment[];
101
+ /** Whether the inbound routing rule was created, already present, or skipped (not configured). */
102
+ routing: {
103
+ created: boolean;
104
+ skipped: boolean;
105
+ };
106
+ }
107
+ /**
108
+ * Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
109
+ * email worker for every managed environment. The order matters — the suppression DB exists and is
110
+ * migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
111
+ *
112
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
113
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
114
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
115
+ */
116
+ export declare function provisionEmail(provisioner: EmailProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<EmailProvisionResult>;
117
+ /** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
118
+ export interface EmailDeprovisioner {
119
+ /** Delete the env's email worker. Idempotent (a missing worker is a no-op). */
120
+ deleteWorker(env: ManagedEnvironment): Promise<void>;
121
+ /**
122
+ * Delete the shared suppression D1. **Destructive** — the global suppression list is lost, so every
123
+ * environment forgets who unsubscribed or hard-bounced — so the orchestration only calls it when
124
+ * explicitly asked. Idempotent.
125
+ */
126
+ deleteSuppressionDatabase(): Promise<void>;
127
+ }
128
+ /** Teardown options. By default the suppression DB is **kept** — losing the global opt-out list is harmful. */
129
+ export interface EmailDeprovisionOptions {
130
+ /** Also delete the shared suppression database. Off by default; only a full destroy sets it. */
131
+ deleteSuppression?: boolean;
132
+ }
133
+ /**
134
+ * Tear down the email infrastructure, reversing {@link provisionEmail}: delete every environment's worker
135
+ * first (they bind the suppression DB), then — only when `deleteSuppression` is set — the shared
136
+ * suppression DB. The suppression list is preserved unless explicitly requested. Idempotent end to end.
137
+ *
138
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
139
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
140
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
141
+ */
142
+ export declare function deprovisionEmail(deprovisioner: EmailDeprovisioner, environments: DeclaredEnvironments | readonly string[], options?: EmailDeprovisionOptions): Promise<void>;
143
+ //# 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,118 @@
1
+ import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
2
+ import { resourceName } from "@pithy-sh/core/src/naming/resource";
3
+ import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
4
+ import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
5
+ //#region src/provision/provisionEmail.ts
6
+ /**
7
+ * The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
8
+ * config wiring. It stands up the durable infrastructure the rest of the capability assumes: the
9
+ * suppression database (one per **project**, bound by every one of that project's environments) and the
10
+ * per-environment prebuilt email worker that hosts the send + scheduler Workflows and the every-minute
11
+ * cron.
12
+ *
13
+ * Unlike `@pithy-sh/secrets`, the email worker needs **no minted CF API token** — it sends through the
14
+ * Cloudflare Email Service `send_email` binding and reads its signing key through the `SECRETS` bindings,
15
+ * neither of which uses an API token. So provisioning here is purely: create + migrate the suppression
16
+ * DB, then deploy each environment's worker.
17
+ *
18
+ * The live Cloudflare/wrangler steps are behind the {@link EmailProvisioner} seam, so the orchestration
19
+ * (order, idempotency contract, per-env fan-out) is unit-tested without touching Cloudflare; the real
20
+ * seam implementation is the live-CF glue, exercised by the integration suite. Every step is idempotent —
21
+ * re-running provisioning is a no-op.
22
+ *
23
+ * **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
24
+ * onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
25
+ * app worker, and the link-signing key must exist (`pithy secrets create email-link-signing-key`). These
26
+ * are one-time account/DNS actions provisioning does not own.
27
+ */
28
+ /** The capability segment every email-owned name carries — the migration namespace and error domain too. */
29
+ const EMAIL_CAPABILITY = "email";
30
+ /**
31
+ * The shared, durable suppression database — **one per project, shared across that project's
32
+ * environments**: `<project>-global-email-suppressions`.
33
+ *
34
+ * The sharing across environments is deliberate and load-bearing. "Do not email this person again" is
35
+ * not an environment-local fact; an address that hard-bounced in production must not be retried from
36
+ * staging, or the sending domain's reputation pays for the distinction. `global` sits in the
37
+ * environment slot to say so out loud rather than by omission.
38
+ *
39
+ * The sharing across **projects** was not deliberate — it was the absence of a project segment. D1's
40
+ * namespace is account-wide and provisioning reuses a database it finds by name, so a fixed
41
+ * `pithy-email-suppressions` meant a second, unrelated Pithy product in the same account silently
42
+ * inherited the first's opt-out list: one product's unsubscribe suppressing another product's
43
+ * transactional mail, with no row anywhere recording why. The project segment gives the scope a
44
+ * definition instead of an accident.
45
+ *
46
+ * Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
47
+ * a D1 database name's limit rather than the single 63 the generic composer defaults to.
48
+ */
49
+ function suppressionDatabaseName(project) {
50
+ return resourceNames(project).global.d1(`${EMAIL_CAPABILITY}-suppressions`);
51
+ }
52
+ /**
53
+ * The name of the inbound Email Routing rule that delivers bounce and complaint mail to the app worker.
54
+ *
55
+ * `global` in the environment slot because there is one rule per zone — the environments are separated
56
+ * by which app Worker the rule points at, not by the rule. Project-scoped and distinct from
57
+ * `@pithy-sh/support`'s `<project>-global-support-inbound`: `ensureWorkerRoute` keys idempotency on the
58
+ * rule *name*, so two projects sharing a zone under one unscoped name would each read the other's rule
59
+ * as their own, and one project's bounces would be delivered to the other's Worker.
60
+ *
61
+ * **The one name here still on the generic composer**, because an Email Routing rule is not a namespace
62
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for. The facade's whole point is
63
+ * that a kind of thing carries its own number; inventing one for this kind would be the opposite. So it
64
+ * takes the conservative default until that namespace lands.
65
+ */
66
+ function bounceRoutingRuleName(project) {
67
+ return resourceName({
68
+ project,
69
+ env: GLOBAL_SCOPE,
70
+ thing: `${EMAIL_CAPABILITY}-bounce`
71
+ });
72
+ }
73
+ /**
74
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
75
+ * through core's naming facade under the **`worker`** namespace (63, the workers.dev cap), which
76
+ * `resolveEmailConfig` also stamps onto the config: one source, so the name the CLI audits and deletes
77
+ * under cannot drift from the name it deploys under. The environment is validated on the way through,
78
+ * so a stale `production` fails here rather than deploying a second host beside the real one.
79
+ */
80
+ function emailWorkerName(project, env) {
81
+ return resourceNames(project).env(env).worker(EMAIL_CAPABILITY);
82
+ }
83
+ /**
84
+ * Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
85
+ * email worker for every managed environment. The order matters — the suppression DB exists and is
86
+ * migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
87
+ *
88
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
89
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
90
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
91
+ */
92
+ async function provisionEmail(provisioner, environments) {
93
+ await provisioner.preflight();
94
+ const { databaseId } = await provisioner.ensureSuppressionDatabase();
95
+ await provisioner.migrateSuppression(databaseId);
96
+ for (const env of managedEnvironments(environments)) await provisioner.deployWorker(env, databaseId);
97
+ const routing = await provisioner.ensureRoutingRule();
98
+ return {
99
+ suppressionDatabaseId: databaseId,
100
+ environments: managedEnvironments(environments),
101
+ routing
102
+ };
103
+ }
104
+ /**
105
+ * Tear down the email infrastructure, reversing {@link provisionEmail}: delete every environment's worker
106
+ * first (they bind the suppression DB), then — only when `deleteSuppression` is set — the shared
107
+ * suppression DB. The suppression list is preserved unless explicitly requested. Idempotent end to end.
108
+ *
109
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
110
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
111
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
112
+ */
113
+ async function deprovisionEmail(deprovisioner, environments, options = {}) {
114
+ for (const env of managedEnvironments(environments)) await deprovisioner.deleteWorker(env);
115
+ if (options.deleteSuppression) await deprovisioner.deleteSuppressionDatabase();
116
+ }
117
+ //#endregion
118
+ export { EMAIL_CAPABILITY, bounceRoutingRuleName, deprovisionEmail, emailWorkerName, provisionEmail, suppressionDatabaseName };
@@ -0,0 +1,122 @@
1
+ import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
2
+ import type { HostD1Binding, HostSecretsStoreBinding, HostSendEmailBinding, HostWorkflowBinding, WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
3
+ import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
4
+ import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
5
+ import type { EmailTheme } from "../templates/theme";
6
+ import { type DevMailDelivery } from "./devDelivery";
7
+ /**
8
+ * The email worker's `wrangler.jsonc` template shape. Email invented the prebuilt-host convention;
9
+ * `@pithy-sh/core`'s {@link WorkflowHostTemplate} is the generalization of it, so this is now that
10
+ * contract with the fields email's committed template always carries narrowed to required. The
11
+ * committed template (`src/workflows/wrangler.jsonc`) stays the source of truth for the static fields
12
+ * (compatibility date, the every-minute cron, class names, the `send_email` binding, theme vars).
13
+ */
14
+ export interface EmailWorkerWranglerTemplate extends WorkflowHostTemplate {
15
+ compatibility_date: string;
16
+ compatibility_flags: string[];
17
+ workers_dev: boolean;
18
+ d1_databases: HostD1Binding[];
19
+ send_email: HostSendEmailBinding[];
20
+ secrets_store_secrets: HostSecretsStoreBinding[];
21
+ workflows: HostWorkflowBinding[];
22
+ triggers: {
23
+ crons: string[];
24
+ };
25
+ vars: Record<string, string>;
26
+ }
27
+ /** The registry the host resolver derives its `workflows` array from, and the host's app dispatches on. */
28
+ export declare const emailWorkflowRegistry: WorkflowRegistry;
29
+ /**
30
+ * The most one Cloudflare Worker variable holds. **Per variable, and that is the whole design.**
31
+ *
32
+ * Cloudflare's documented limit is 5 KB per variable, on Free and Paid alike, and a Worker carries 64
33
+ * of them on Free and 128 on Paid. The failure it produces is API error 10054 at upload — a wrangler
34
+ * exit nobody can act on, in the middle of a provision run that has already created databases.
35
+ *
36
+ * So each locale travels in its own variable. One pack of the kit's Spanish is about 3 KB, which
37
+ * leaves 2 KB of room inside its own ceiling, and twenty languages is twenty variables rather than one
38
+ * 62 KB value that is refused outright. The host renders one email in one locale and never needs the
39
+ * other nineteen, so nothing is paid for the split.
40
+ *
41
+ * The check below therefore guards what it should: a single language pack growing past what a variable
42
+ * holds, which would take the kit's email copy growing by about two thirds. It is deliberately a
43
+ * refusal and not a truncation — a shortened catalog is a letter half in Spanish and half in English,
44
+ * with nothing anywhere failing to say so.
45
+ */
46
+ export declare const MAX_WORKER_VAR_BYTES: number;
47
+ /**
48
+ * One `EMAIL_MESSAGES_<LOCALE>` var per locale, or nothing when the project has no catalogs to carry.
49
+ *
50
+ * A locale with an empty catalog is omitted rather than written as `"{}"`: the host reads an absent
51
+ * variable as the kit's English, which is exactly what that means, and an empty object in the deployed
52
+ * config reads like a value somebody failed to fill.
53
+ *
54
+ * **Exported because this is not the only host that carries them.** `@pithy-sh/testers`' daily-pass
55
+ * worker reads the same variables through the same `catalogsFromEnv` seam, against the same ceiling —
56
+ * so the limit, the naming and the refusal are composed here once rather than restated there, where
57
+ * the second copy is the one that drifts.
58
+ */
59
+ export declare function emailMessagesVars(messages: LocaleCatalogs | undefined): Record<string, string>;
60
+ /** The resolved resource ids + per-env values for one environment's email-worker deploy. */
61
+ export interface EmailConfigParams {
62
+ /**
63
+ * The project name — the `<project>` segment the worker, both Workflows, and the suppression
64
+ * database name lead with. The root `pithy.config.ts` `name`, resolved by `requireProjectName` and
65
+ * never guessed: Worker script and Workflow names are account-scoped, so a wrong value here
66
+ * overwrites another project's running email host.
67
+ */
68
+ project: string;
69
+ /**
70
+ * The environment being resolved. `dev` as well as a deployed one: `pithy dev` resolves this same
71
+ * template into the local host config it runs, which is what {@link EmailConfigParams.devDelivery}
72
+ * governs.
73
+ */
74
+ env: ManagedEnvironment | "dev";
75
+ /** The app database id for this environment — where jobs/events live. */
76
+ appDatabaseId: string;
77
+ /** The shared suppression database id (same in every environment). */
78
+ suppressionDatabaseId: string;
79
+ /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the signing key. */
80
+ secretsDatabaseId: string;
81
+ /** The CF Secrets Store id holding the per-env master key. */
82
+ storeId: string;
83
+ /** The app worker's public base URL for this environment — callback links are built against it. */
84
+ baseUrl: string;
85
+ /** The resolved brand theme — serialized into the worker's `EMAIL_THEME` var. */
86
+ theme: EmailTheme;
87
+ /**
88
+ * This project's email catalogs — serialized into the worker's `EMAIL_MESSAGES` var.
89
+ *
90
+ * The same journey `theme` makes, and for the same reason: the host composes no capabilities, so
91
+ * anything the adopter configured has to arrive as data. `emailHostCatalogs` builds it from the
92
+ * composed project's layers; a project that composed no i18n capability passes `{}` or omits it, and
93
+ * the var is not written at all.
94
+ */
95
+ messages?: LocaleCatalogs;
96
+ /**
97
+ * What the host's `send_email` binding does under `pithy dev` — the adopter's `email({ devDelivery })`.
98
+ * Defaults to `remote`, which sends real mail from the developer's machine. Ignored outside `dev`.
99
+ */
100
+ devDelivery?: DevMailDelivery;
101
+ }
102
+ /**
103
+ * Resolve the email-worker `wrangler.jsonc` template into one environment's standalone config — no
104
+ * `[env.*]` stanzas (staging and prod are genuinely separate workers, per CLAUDE.md).
105
+ *
106
+ * The mechanics are `@pithy-sh/core`'s {@link resolveWorkflowHost}: this is the email-shaped face of
107
+ * it, mapping email's seven inputs onto the generic host params. What stays here is the part that is
108
+ * genuinely email's — which binding takes which database id, and the `@pithy-sh/secrets` import that
109
+ * names the env-scoped master key. Core must never depend on `@pithy-sh/secrets`, so the resolved
110
+ * string is passed in rather than the naming rule being hoisted.
111
+ *
112
+ * `send_email`'s `remote` flag is the one thing here that is a *decision* rather than a fill: real
113
+ * delivery is the default in every environment, and `dev` alone may choose the local simulator
114
+ * instead (`devDelivery.ts`).
115
+ *
116
+ * Only `EMAIL_SUPPRESSIONS`'s `database_name` is rewritten. That database is email's own, and its name
117
+ * now carries the project — leaving the template's `pithy-email-suppressions` in place would print a
118
+ * name no account holds. `pithy-app` and `pithy-secrets` are owned elsewhere and pass through
119
+ * untouched; only their ids differ per environment.
120
+ */
121
+ export declare function resolveEmailConfig(template: EmailWorkerWranglerTemplate, params: EmailConfigParams): EmailWorkerWranglerTemplate;
122
+ //# 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,124 @@
1
+ import { emailCatalogVarName } from "../templates/messages.js";
2
+ import { emailRemoteBindings } from "./devDelivery.js";
3
+ import { EMAIL_CAPABILITY, suppressionDatabaseName } from "./provisionEmail.js";
4
+ import { EmailScheduleParams, EmailSendParams } from "../workflows/params.js";
5
+ import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
6
+ import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
7
+ import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
8
+ import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
9
+ /** The registry the host resolver derives its `workflows` array from, and the host's app dispatches on. */
10
+ const emailWorkflowRegistry = Object.fromEntries(Object.entries({
11
+ send: {
12
+ binding: "EMAIL_SENDER",
13
+ className: "EmailSendWorkflow",
14
+ params: EmailSendParams
15
+ },
16
+ schedule: {
17
+ binding: "EMAIL_SCHEDULER",
18
+ className: "EmailSchedulerWorkflow",
19
+ params: EmailScheduleParams,
20
+ schedule: "* * * * *"
21
+ }
22
+ }).map(([job, spec]) => {
23
+ const key = workflowKey(EMAIL_CAPABILITY, job);
24
+ return [key, {
25
+ key,
26
+ capability: EMAIL_CAPABILITY,
27
+ job,
28
+ spec
29
+ }];
30
+ }));
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
+ const MAX_WORKER_VAR_BYTES = 5120;
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
+ function emailMessagesVars(messages) {
62
+ if (!messages) return {};
63
+ const vars = {};
64
+ for (const [locale, catalog] of Object.entries(messages)) {
65
+ if (!catalog || Object.keys(catalog).length === 0) continue;
66
+ const serialized = JSON.stringify(catalog);
67
+ const bytes = new TextEncoder().encode(serialized).length;
68
+ if (bytes > 5120) throw new ValidationError({
69
+ message: `The \`${locale}\` email catalog is ${bytes} bytes; a Cloudflare Worker variable holds ${MAX_WORKER_VAR_BYTES}.`,
70
+ action: `Shorten the \`email/\` sentences for \`${locale}\` in i18n({ messages }), or drop that locale from supportedLocales.`,
71
+ detail: `${emailCatalogVarName(locale)} serialized to ${bytes} bytes over the ${MAX_WORKER_VAR_BYTES}-byte limit; Cloudflare refuses the upload with error 10054.`
72
+ });
73
+ vars[emailCatalogVarName(locale)] = serialized;
74
+ }
75
+ return vars;
76
+ }
77
+ /**
78
+ * Resolve the email-worker `wrangler.jsonc` template into one environment's standalone config — no
79
+ * `[env.*]` stanzas (staging and prod are genuinely separate workers, per CLAUDE.md).
80
+ *
81
+ * The mechanics are `@pithy-sh/core`'s {@link resolveWorkflowHost}: this is the email-shaped face of
82
+ * it, mapping email's seven inputs onto the generic host params. What stays here is the part that is
83
+ * genuinely email's — which binding takes which database id, and the `@pithy-sh/secrets` import that
84
+ * names the env-scoped master key. Core must never depend on `@pithy-sh/secrets`, so the resolved
85
+ * string is passed in rather than the naming rule being hoisted.
86
+ *
87
+ * `send_email`'s `remote` flag is the one thing here that is a *decision* rather than a fill: real
88
+ * delivery is the default in every environment, and `dev` alone may choose the local simulator
89
+ * instead (`devDelivery.ts`).
90
+ *
91
+ * Only `EMAIL_SUPPRESSIONS`'s `database_name` is rewritten. That database is email's own, and its name
92
+ * now carries the project — leaving the template's `pithy-email-suppressions` in place would print a
93
+ * name no account holds. `pithy-app` and `pithy-secrets` are owned elsewhere and pass through
94
+ * untouched; only their ids differ per environment.
95
+ */
96
+ function resolveEmailConfig(template, params) {
97
+ const { project, env, appDatabaseId, suppressionDatabaseId, secretsDatabaseId, storeId, baseUrl, theme } = params;
98
+ return resolveWorkflowHost(template, {
99
+ project,
100
+ capability: EMAIL_CAPABILITY,
101
+ env,
102
+ databaseIds: {
103
+ DB: appDatabaseId,
104
+ EMAIL_SUPPRESSIONS: suppressionDatabaseId,
105
+ SECRETS: secretsDatabaseId
106
+ },
107
+ databaseNames: { EMAIL_SUPPRESSIONS: suppressionDatabaseName(project) },
108
+ secretsStoreId: storeId,
109
+ masterKeySecretName: masterKeySecretName(project, env),
110
+ vars: {
111
+ EMAIL_THEME: JSON.stringify(theme),
112
+ BASE_URL: baseUrl,
113
+ ...emailMessagesVars(params.messages)
114
+ },
115
+ remoteBindings: emailRemoteBindings(env, params.devDelivery ?? "remote"),
116
+ workflows: hostWorkflowsFor(emailWorkflowRegistry, {
117
+ project,
118
+ capability: EMAIL_CAPABILITY,
119
+ env
120
+ }).workflows
121
+ });
122
+ }
123
+ //#endregion
124
+ export { MAX_WORKER_VAR_BYTES, emailMessagesVars, emailWorkflowRegistry, resolveEmailConfig };
@@ -0,0 +1,40 @@
1
+ import type { CapabilitySettings } from "@pithy-sh/core/src/capability/settings";
2
+ import type { EmailTheme } from "../templates/theme";
3
+ /**
4
+ * Whether email's settings **work**, as `pithy doctor` asks it (pithy-sh/pithy#411).
5
+ *
6
+ * Every check doctor had before this one asked about presence: the `email({ … })` option keys are
7
+ * written, the `DB` and `EMAIL_SENDER` bindings are declared, the ledger is level. All of them pass while
8
+ * `fromAddress` names a domain nobody onboarded, the link-signing key was never created, `BASE_URL` is
9
+ * staging's URL in production's config, and the suppression database does not exist — and the way an
10
+ * adopter learns any of that is a message that never arrives.
11
+ *
12
+ * ## The local tier runs the host's own schema
13
+ *
14
+ * `checkHostEnv(emailHostEnv, …)` is not a second reading of the same rules — it is *the* reading. The
15
+ * prebuilt host worker refuses to start on the same declaration (`workflows/worker.ts`), so a value doctor
16
+ * calls good is a value the host will accept, and a rule that changes changes in one file. Bindings are
17
+ * stubbed on the way in, deliberately: whether `DB` is bound is `pithy doctor`'s `bindings` check and
18
+ * `Secret bindings:` block, and asking it twice would report one fault as two.
19
+ *
20
+ * ## The account tier asks the three things only the account knows
21
+ *
22
+ * Is the sending domain a zone here, does the suppression database exist, does the signing key have a
23
+ * value. Each costs one Cloudflare call, each is skipped whole when the account cannot be reached, and
24
+ * none of them is inferable from a file in the checkout.
25
+ *
26
+ * Nothing here writes. Every finding names the command, the config key, or the one-time dashboard action
27
+ * that resolves it.
28
+ */
29
+ /** The resolved config slice the check reads. The capability builds it; nothing here parses config. */
30
+ export interface EmailSettingsInput {
31
+ /** The address every message is sent from — its domain is what must be onboarded. */
32
+ fromAddress: string;
33
+ /** The public base URL every link in a message is built against. */
34
+ baseUrl: string;
35
+ /** The resolved theme, as the host receives it: one JSON var. */
36
+ theme?: EmailTheme;
37
+ }
38
+ /** Email's settings check, built from one composition's resolved config. Declared on the capability. */
39
+ export declare function emailSettings(config: EmailSettingsInput): CapabilitySettings;
40
+ //# sourceMappingURL=settingsCheck.d.ts.map
@@ -0,0 +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;AAIhD,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;AAyJD,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAK5E"}