@pithy-sh/email 0.1.1 → 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.
- package/dist/analytics.d.ts +19 -0
- package/dist/analytics.d.ts.map +1 -0
- package/dist/analytics.js +13 -0
- package/dist/audit/actions.d.ts +45 -0
- package/dist/audit/actions.d.ts.map +1 -0
- package/dist/audit/actions.js +45 -0
- package/dist/bounce/classify.d.ts +38 -0
- package/dist/bounce/classify.d.ts.map +1 -0
- package/dist/bounce/classify.js +46 -0
- package/dist/bounce/handler.d.ts +32 -0
- package/dist/bounce/handler.d.ts.map +1 -0
- package/dist/bounce/handler.js +81 -0
- package/dist/capability.d.ts +158 -0
- package/dist/capability.d.ts.map +1 -0
- package/dist/capability.js +255 -0
- package/dist/crypto/signingKey.d.ts +36 -0
- package/dist/crypto/signingKey.d.ts.map +1 -0
- package/dist/crypto/signingKey.js +36 -0
- package/dist/crypto/token.d.ts +47 -0
- package/dist/crypto/token.d.ts.map +1 -0
- package/dist/crypto/token.js +99 -0
- package/dist/data/emailEvent.d.ts +28 -0
- package/dist/data/emailEvent.d.ts.map +1 -0
- package/dist/data/emailEvent.js +22 -0
- package/dist/data/emailJob.d.ts +76 -0
- package/dist/data/emailJob.d.ts.map +1 -0
- package/dist/data/emailJob.js +62 -0
- package/dist/data/emailSuppression.d.ts +23 -0
- package/dist/data/emailSuppression.d.ts.map +1 -0
- package/dist/data/emailSuppression.js +21 -0
- package/dist/data/enums.d.ts +76 -0
- package/dist/data/enums.d.ts.map +1 -0
- package/dist/data/enums.js +65 -0
- package/dist/data/tables.d.ts +114 -0
- package/dist/data/tables.d.ts.map +1 -0
- package/dist/data/tables.js +30 -0
- package/dist/error/errors.d.ts +60 -0
- package/dist/error/errors.d.ts.map +1 -0
- package/dist/error/errors.js +82 -0
- package/dist/http/callbacks.d.ts +21 -0
- package/dist/http/callbacks.d.ts.map +1 -0
- package/dist/http/callbacks.js +110 -0
- package/dist/http/guards.d.ts +99 -0
- package/dist/http/guards.d.ts.map +1 -0
- package/dist/http/guards.js +144 -0
- package/dist/http/responses.d.ts +295 -0
- package/dist/http/responses.d.ts.map +1 -0
- package/dist/http/responses.js +115 -0
- package/dist/http/routes.d.ts +71 -0
- package/dist/http/routes.d.ts.map +1 -0
- package/dist/http/routes.js +292 -0
- package/dist/http/schemas.d.ts +90 -0
- package/dist/http/schemas.d.ts.map +1 -0
- package/dist/http/schemas.js +91 -0
- package/dist/http/view.d.ts +78 -0
- package/dist/http/view.d.ts.map +1 -0
- package/dist/http/view.js +130 -0
- package/dist/index.d.ts +46 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/jobs/read.d.ts +191 -0
- package/dist/jobs/read.d.ts.map +1 -0
- package/dist/jobs/read.js +143 -0
- package/dist/jobs/retry.d.ts +99 -0
- package/dist/jobs/retry.d.ts.map +1 -0
- package/dist/jobs/retry.js +67 -0
- package/dist/migrations/0001_init.d.ts +32 -0
- package/dist/migrations/0001_init.d.ts.map +1 -0
- package/dist/migrations/0001_init.js +60 -0
- package/dist/migrations/0001_suppressions.d.ts +10 -0
- package/dist/migrations/0001_suppressions.d.ts.map +1 -0
- package/dist/migrations/0001_suppressions.js +20 -0
- package/dist/provision/devDelivery.d.ts +32 -0
- package/dist/provision/devDelivery.d.ts.map +1 -0
- package/dist/provision/devDelivery.js +37 -0
- package/dist/provision/hostCatalogs.d.ts +10 -0
- package/dist/provision/hostCatalogs.d.ts.map +1 -0
- package/dist/provision/hostCatalogs.js +78 -0
- package/dist/provision/provisionEmail.d.ts +143 -0
- package/dist/provision/provisionEmail.d.ts.map +1 -0
- package/dist/provision/provisionEmail.js +118 -0
- package/dist/provision/resolveEmailConfig.d.ts +122 -0
- package/dist/provision/resolveEmailConfig.d.ts.map +1 -0
- package/dist/provision/resolveEmailConfig.js +124 -0
- package/dist/provision/settingsCheck.d.ts +40 -0
- package/dist/provision/settingsCheck.d.ts.map +1 -0
- package/dist/provision/settingsCheck.js +138 -0
- package/dist/send/batchIdentity.d.ts +42 -0
- package/dist/send/batchIdentity.d.ts.map +1 -0
- package/dist/send/batchIdentity.js +46 -0
- package/dist/send/enqueue.d.ts +216 -0
- package/dist/send/enqueue.d.ts.map +1 -0
- package/dist/send/enqueue.js +153 -0
- package/dist/send/errorMapping.d.ts +27 -0
- package/dist/send/errorMapping.d.ts.map +1 -0
- package/dist/send/errorMapping.js +52 -0
- package/dist/send/events.d.ts +15 -0
- package/dist/send/events.d.ts.map +1 -0
- package/dist/send/events.js +17 -0
- package/dist/send/fromComposition.d.ts +47 -0
- package/dist/send/fromComposition.d.ts.map +1 -0
- package/dist/send/fromComposition.js +53 -0
- package/dist/send/retryPolicy.d.ts +32 -0
- package/dist/send/retryPolicy.d.ts.map +1 -0
- package/dist/send/retryPolicy.js +39 -0
- package/dist/send/runSend.d.ts +106 -0
- package/dist/send/runSend.d.ts.map +1 -0
- package/dist/send/runSend.js +218 -0
- package/dist/send/sendAt.d.ts +6 -0
- package/dist/send/sendAt.d.ts.map +1 -0
- package/dist/send/sendAt.js +62 -0
- package/dist/send/sender.d.ts +42 -0
- package/dist/send/sender.d.ts.map +1 -0
- package/dist/send/sender.js +0 -0
- package/dist/send/senderBinding.d.ts +44 -0
- package/dist/send/senderBinding.d.ts.map +1 -0
- package/dist/send/senderBinding.js +21 -0
- package/dist/send/suppression.d.ts +93 -0
- package/dist/send/suppression.d.ts.map +1 -0
- package/dist/send/suppression.js +132 -0
- package/dist/templates/engine.d.ts +109 -0
- package/dist/templates/engine.d.ts.map +1 -0
- package/dist/templates/engine.js +258 -0
- package/dist/templates/messages.d.ts +94 -0
- package/dist/templates/messages.d.ts.map +1 -0
- package/dist/templates/messages.es.d.ts +29 -0
- package/dist/templates/messages.es.d.ts.map +1 -0
- package/dist/templates/messages.es.js +82 -0
- package/dist/templates/messages.js +266 -0
- package/dist/templates/partials.d.ts +5 -0
- package/dist/templates/partials.d.ts.map +1 -0
- package/dist/templates/partials.js +59 -0
- package/dist/templates/precompiled.generated.d.ts +266 -0
- package/dist/templates/precompiled.generated.d.ts.map +1 -0
- package/dist/templates/precompiled.generated.js +4039 -0
- package/dist/templates/registry.d.ts +118 -0
- package/dist/templates/registry.d.ts.map +1 -0
- package/dist/templates/registry.js +323 -0
- package/dist/templates/samples.d.ts +7 -0
- package/dist/templates/samples.d.ts.map +1 -0
- package/dist/templates/samples.js +98 -0
- package/dist/templates/severity.d.ts +40 -0
- package/dist/templates/severity.d.ts.map +1 -0
- package/dist/templates/severity.js +81 -0
- package/dist/templates/theme.d.ts +193 -0
- package/dist/templates/theme.d.ts.map +1 -0
- package/dist/templates/theme.js +168 -0
- package/dist/version.generated.d.ts +5 -0
- package/dist/version.generated.d.ts.map +1 -0
- package/dist/version.generated.js +7 -0
- package/dist/workflows/hostApp.d.ts +33 -0
- package/dist/workflows/hostApp.d.ts.map +1 -0
- package/dist/workflows/hostApp.js +19 -0
- package/dist/workflows/hostEnv.d.ts +129 -0
- package/dist/workflows/hostEnv.d.ts.map +1 -0
- package/dist/workflows/hostEnv.js +147 -0
- package/dist/workflows/instanceLiveness.d.ts +3 -0
- package/dist/workflows/instanceLiveness.d.ts.map +1 -0
- package/dist/workflows/instanceLiveness.js +37 -0
- package/dist/workflows/instances.d.ts +18 -0
- package/dist/workflows/instances.d.ts.map +1 -0
- package/dist/workflows/instances.js +0 -0
- package/dist/workflows/params.d.ts +23 -0
- package/dist/workflows/params.d.ts.map +1 -0
- package/dist/workflows/params.js +21 -0
- package/dist/workflows/scheduler.d.ts +82 -0
- package/dist/workflows/scheduler.d.ts.map +1 -0
- package/dist/workflows/scheduler.js +111 -0
- package/dist/workflows/sendBatch.d.ts +85 -0
- package/dist/workflows/sendBatch.d.ts.map +1 -0
- package/dist/workflows/sendBatch.js +50 -0
- package/dist/workflows/worker.d.ts +100 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +117 -0
- package/package.json +22 -11
- 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"}
|