@pithy-sh/email 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/analytics.d.ts +21 -0
- package/dist/analytics.d.ts.map +1 -0
- package/dist/analytics.js +15 -0
- package/dist/audit/actions.d.ts +47 -0
- package/dist/audit/actions.d.ts.map +1 -0
- package/dist/audit/actions.js +47 -0
- package/dist/bounce/classify.d.ts +40 -0
- package/dist/bounce/classify.d.ts.map +1 -0
- package/dist/bounce/classify.js +48 -0
- package/dist/bounce/handler.d.ts +34 -0
- package/dist/bounce/handler.d.ts.map +1 -0
- package/dist/bounce/handler.js +83 -0
- package/dist/capability.d.ts +160 -0
- package/dist/capability.d.ts.map +1 -0
- package/dist/capability.js +257 -0
- package/dist/crypto/signingKey.d.ts +38 -0
- package/dist/crypto/signingKey.d.ts.map +1 -0
- package/dist/crypto/signingKey.js +38 -0
- package/dist/crypto/token.d.ts +49 -0
- package/dist/crypto/token.d.ts.map +1 -0
- package/dist/crypto/token.js +101 -0
- package/dist/data/emailEvent.d.ts +30 -0
- package/dist/data/emailEvent.d.ts.map +1 -0
- package/dist/data/emailEvent.js +24 -0
- package/dist/data/emailJob.d.ts +78 -0
- package/dist/data/emailJob.d.ts.map +1 -0
- package/dist/data/emailJob.js +64 -0
- package/dist/data/emailSuppression.d.ts +25 -0
- package/dist/data/emailSuppression.d.ts.map +1 -0
- package/dist/data/emailSuppression.js +23 -0
- package/dist/data/enums.d.ts +78 -0
- package/dist/data/enums.d.ts.map +1 -0
- package/dist/data/enums.js +67 -0
- package/dist/data/tables.d.ts +116 -0
- package/dist/data/tables.d.ts.map +1 -0
- package/dist/data/tables.js +32 -0
- package/dist/error/errors.d.ts +62 -0
- package/dist/error/errors.d.ts.map +1 -0
- package/dist/error/errors.js +84 -0
- package/dist/http/callbacks.d.ts +23 -0
- package/dist/http/callbacks.d.ts.map +1 -0
- package/dist/http/callbacks.js +112 -0
- package/dist/http/guards.d.ts +101 -0
- package/dist/http/guards.d.ts.map +1 -0
- package/dist/http/guards.js +146 -0
- package/dist/http/responses.d.ts +297 -0
- package/dist/http/responses.d.ts.map +1 -0
- package/dist/http/responses.js +117 -0
- package/dist/http/routes.d.ts +73 -0
- package/dist/http/routes.d.ts.map +1 -0
- package/dist/http/routes.js +294 -0
- package/dist/http/schemas.d.ts +92 -0
- package/dist/http/schemas.d.ts.map +1 -0
- package/dist/http/schemas.js +93 -0
- package/dist/http/view.d.ts +80 -0
- package/dist/http/view.d.ts.map +1 -0
- package/dist/http/view.js +132 -0
- package/dist/index.d.ts +48 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +13 -0
- package/dist/jobs/read.d.ts +193 -0
- package/dist/jobs/read.d.ts.map +1 -0
- package/dist/jobs/read.js +145 -0
- package/dist/jobs/retry.d.ts +101 -0
- package/dist/jobs/retry.d.ts.map +1 -0
- package/dist/jobs/retry.js +69 -0
- package/dist/migrations/0001_init.d.ts +34 -0
- package/dist/migrations/0001_init.d.ts.map +1 -0
- package/dist/migrations/0001_init.js +62 -0
- package/dist/migrations/0001_suppressions.d.ts +12 -0
- package/dist/migrations/0001_suppressions.d.ts.map +1 -0
- package/dist/migrations/0001_suppressions.js +22 -0
- package/dist/provision/devDelivery.d.ts +34 -0
- package/dist/provision/devDelivery.d.ts.map +1 -0
- package/dist/provision/devDelivery.js +39 -0
- package/dist/provision/hostCatalogs.d.ts +12 -0
- package/dist/provision/hostCatalogs.d.ts.map +1 -0
- package/dist/provision/hostCatalogs.js +80 -0
- package/dist/provision/provisionEmail.d.ts +145 -0
- package/dist/provision/provisionEmail.d.ts.map +1 -0
- package/dist/provision/provisionEmail.js +120 -0
- package/dist/provision/resolveEmailConfig.d.ts +124 -0
- package/dist/provision/resolveEmailConfig.d.ts.map +1 -0
- package/dist/provision/resolveEmailConfig.js +126 -0
- package/dist/provision/settingsCheck.d.ts +42 -0
- package/dist/provision/settingsCheck.d.ts.map +1 -0
- package/dist/provision/settingsCheck.js +140 -0
- package/dist/send/batchIdentity.d.ts +44 -0
- package/dist/send/batchIdentity.d.ts.map +1 -0
- package/dist/send/batchIdentity.js +48 -0
- package/dist/send/enqueue.d.ts +218 -0
- package/dist/send/enqueue.d.ts.map +1 -0
- package/dist/send/enqueue.js +155 -0
- package/dist/send/errorMapping.d.ts +29 -0
- package/dist/send/errorMapping.d.ts.map +1 -0
- package/dist/send/errorMapping.js +54 -0
- package/dist/send/events.d.ts +17 -0
- package/dist/send/events.d.ts.map +1 -0
- package/dist/send/events.js +19 -0
- package/dist/send/fromComposition.d.ts +49 -0
- package/dist/send/fromComposition.d.ts.map +1 -0
- package/dist/send/fromComposition.js +55 -0
- package/dist/send/retryPolicy.d.ts +34 -0
- package/dist/send/retryPolicy.d.ts.map +1 -0
- package/dist/send/retryPolicy.js +41 -0
- package/dist/send/runSend.d.ts +108 -0
- package/dist/send/runSend.d.ts.map +1 -0
- package/dist/send/runSend.js +220 -0
- package/dist/send/sendAt.d.ts +8 -0
- package/dist/send/sendAt.d.ts.map +1 -0
- package/dist/send/sendAt.js +64 -0
- package/dist/send/sender.d.ts +44 -0
- package/dist/send/sender.d.ts.map +1 -0
- package/dist/send/sender.js +2 -0
- package/dist/send/senderBinding.d.ts +46 -0
- package/dist/send/senderBinding.d.ts.map +1 -0
- package/dist/send/senderBinding.js +23 -0
- package/dist/send/suppression.d.ts +95 -0
- package/dist/send/suppression.d.ts.map +1 -0
- package/dist/send/suppression.js +134 -0
- package/dist/templates/engine.d.ts +111 -0
- package/dist/templates/engine.d.ts.map +1 -0
- package/dist/templates/engine.js +260 -0
- package/dist/templates/messages.d.ts +96 -0
- package/dist/templates/messages.d.ts.map +1 -0
- package/dist/templates/messages.es.d.ts +31 -0
- package/dist/templates/messages.es.d.ts.map +1 -0
- package/dist/templates/messages.es.js +84 -0
- package/dist/templates/messages.js +268 -0
- package/dist/templates/partials.d.ts +7 -0
- package/dist/templates/partials.d.ts.map +1 -0
- package/dist/templates/partials.js +61 -0
- package/dist/templates/precompiled.generated.d.ts +268 -0
- package/dist/templates/precompiled.generated.d.ts.map +1 -0
- package/dist/templates/precompiled.generated.js +4041 -0
- package/dist/templates/registry.d.ts +120 -0
- package/dist/templates/registry.d.ts.map +1 -0
- package/dist/templates/registry.js +325 -0
- package/dist/templates/samples.d.ts +9 -0
- package/dist/templates/samples.d.ts.map +1 -0
- package/dist/templates/samples.js +100 -0
- package/dist/templates/severity.d.ts +42 -0
- package/dist/templates/severity.d.ts.map +1 -0
- package/dist/templates/severity.js +83 -0
- package/dist/templates/theme.d.ts +195 -0
- package/dist/templates/theme.d.ts.map +1 -0
- package/dist/templates/theme.js +170 -0
- package/dist/version.generated.d.ts +7 -0
- package/dist/version.generated.d.ts.map +1 -0
- package/dist/version.generated.js +9 -0
- package/dist/workflows/hostApp.d.ts +35 -0
- package/dist/workflows/hostApp.d.ts.map +1 -0
- package/dist/workflows/hostApp.js +21 -0
- package/dist/workflows/hostEnv.d.ts +131 -0
- package/dist/workflows/hostEnv.d.ts.map +1 -0
- package/dist/workflows/hostEnv.js +149 -0
- package/dist/workflows/instanceLiveness.d.ts +5 -0
- package/dist/workflows/instanceLiveness.d.ts.map +1 -0
- package/dist/workflows/instanceLiveness.js +39 -0
- package/dist/workflows/instances.d.ts +20 -0
- package/dist/workflows/instances.d.ts.map +1 -0
- package/dist/workflows/instances.js +2 -0
- package/dist/workflows/params.d.ts +25 -0
- package/dist/workflows/params.d.ts.map +1 -0
- package/dist/workflows/params.js +23 -0
- package/dist/workflows/scheduler.d.ts +84 -0
- package/dist/workflows/scheduler.d.ts.map +1 -0
- package/dist/workflows/scheduler.js +113 -0
- package/dist/workflows/sendBatch.d.ts +87 -0
- package/dist/workflows/sendBatch.d.ts.map +1 -0
- package/dist/workflows/sendBatch.js +52 -0
- package/dist/workflows/worker.d.ts +102 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +119 -0
- package/package.json +22 -11
- package/src/version.generated.ts +1 -1
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { EmailJob } from "../data/emailJob.js";
|
|
4
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
|
+
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
6
|
+
import { decodeCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
|
|
7
|
+
//#region src/jobs/read.ts
|
|
8
|
+
/**
|
|
9
|
+
* A cursor this table can actually resume from.
|
|
10
|
+
*
|
|
11
|
+
* `PageCursor.sort` is a union because Better Auth stores ISO text where Pithy's own tables store
|
|
12
|
+
* ms-epoch numbers, and comparing a string against an integer column in SQLite silently orders by
|
|
13
|
+
* something nobody meant. Jobs store a number, so anything else is treated exactly as a malformed
|
|
14
|
+
* cursor is: undefined, and the caller gets a first page.
|
|
15
|
+
*/
|
|
16
|
+
function jobCursor(raw) {
|
|
17
|
+
const cursor = decodeCursor(raw);
|
|
18
|
+
if (!cursor || typeof cursor.sort !== "number") return void 0;
|
|
19
|
+
return {
|
|
20
|
+
sort: cursor.sort,
|
|
21
|
+
id: String(cursor.id)
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
/** One page of jobs, newest first, optionally filtered to one status. */
|
|
25
|
+
async function listJobs(db, filter) {
|
|
26
|
+
const limit = pageLimit(filter.limit);
|
|
27
|
+
const after = jobCursor(filter.cursor);
|
|
28
|
+
let query = db.selectFrom("pithyEmailJobs").selectAll().orderBy("createdAt", "desc").orderBy("id", "desc").limit(limit + 1);
|
|
29
|
+
if (filter.status) query = query.where("status", "=", filter.status);
|
|
30
|
+
if (after) query = query.where((eb) => eb.or([eb("createdAt", "<", after.sort), eb.and([eb("createdAt", "=", after.sort), eb("id", "<", after.id)])]));
|
|
31
|
+
const jobs = (await query.execute()).map((row) => EmailJob.parse(row));
|
|
32
|
+
return toPage(jobs, limit, (job) => ({
|
|
33
|
+
sort: job.createdAt.getTime(),
|
|
34
|
+
id: job.id
|
|
35
|
+
}));
|
|
36
|
+
}
|
|
37
|
+
/** One job by id, or undefined. The caller decides what a miss means. */
|
|
38
|
+
async function getJob(db, jobId) {
|
|
39
|
+
const row = await db.selectFrom("pithyEmailJobs").selectAll().where("id", "=", jobId).executeTakeFirst();
|
|
40
|
+
return row ? EmailJob.parse(row) : void 0;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* ## `sentSince` — has this message already gone out
|
|
44
|
+
*
|
|
45
|
+
* The narrow read, for the caller deciding whether to send. A transactional notice that must not repeat,
|
|
46
|
+
* and must be *corrected* if the thing it announced stops being true, cannot be decided from a flag of
|
|
47
|
+
* the caller's own: a `cancellationNoticeSentAt` column is a second answer to a question this table
|
|
48
|
+
* already holds the first of, and the two disagree the first time a send fails after the flag is
|
|
49
|
+
* written. `pithy_email_jobs` is the record; this is the read over it, so nobody has to define its shape
|
|
50
|
+
* a second time in their own repository.
|
|
51
|
+
*
|
|
52
|
+
* ## Two axes, because a template is not always one message
|
|
53
|
+
*
|
|
54
|
+
* It was `(to, template)` alone, and that could not finish its only intended consumer (pithy-sh/pithy#382).
|
|
55
|
+
* Six account notices ride one `operationalNotice` to the same addresses, so the template id does not
|
|
56
|
+
* separate them; `correlation` is the enqueue-side discriminator that does. See {@link SentSubject} for
|
|
57
|
+
* why the two are a union and not three optional fields.
|
|
58
|
+
*
|
|
59
|
+
* **The direction of the failure is why this was worth a column.** The dashboard uses the answer
|
|
60
|
+
* *positively*: the correction letter goes out only when the letter it corrects already did. An
|
|
61
|
+
* under-report there sends nothing at all — it withholds the correction from somebody holding a letter
|
|
62
|
+
* that has stopped being true. That is silence, to the one person owed the message, and silence is the
|
|
63
|
+
* failure nobody finds in production.
|
|
64
|
+
*
|
|
65
|
+
* ## Four columns, and every other one is a deliberate no
|
|
66
|
+
*
|
|
67
|
+
* `SentSummary` is `EmailJob.pick(…)`, so the columns it carries are the columns it selects and a
|
|
68
|
+
* projection cannot leak one it never loaded. What is not on it:
|
|
69
|
+
*
|
|
70
|
+
* - **`toAddress`.** The caller passed the address in; handing it back means a read answering a question
|
|
71
|
+
* about one person returns a copy of them in every row, and any log of the result is an address list.
|
|
72
|
+
* - **`payload`.** The sign-in link and the OTP. `view.ts` argues this at length and the argument is the
|
|
73
|
+
* same here, except that this reader is reachable from ordinary application code rather than only from
|
|
74
|
+
* a scoped credential, which makes it stronger rather than weaker.
|
|
75
|
+
* - **`subject`.** Rendered content, and the temptation is specific: it is the only per-row string that
|
|
76
|
+
* distinguishes two messages sharing a template, so a caller needing that discrimination would match
|
|
77
|
+
* on it. That match breaks on a copy edit, silently, in the direction of sending again. Discriminating
|
|
78
|
+
* two notices was the enqueue side's problem and now has an enqueue-side answer — `correlation`
|
|
79
|
+
* (#382) — rather than a rendered string exported to be string-matched.
|
|
80
|
+
* - **`messageId`, `error`, `bounceCode`.** The provider's own words. A provider error routinely embeds
|
|
81
|
+
* the recipient, which is why the list view carries `failed` rather than the text.
|
|
82
|
+
*
|
|
83
|
+
* `status` rather than a boolean, because the statuses are the answer: a `failed` or `suppressed` row is
|
|
84
|
+
* an email nobody read, and a reader that collapsed the log to "yes" would treat it as one they did.
|
|
85
|
+
*
|
|
86
|
+
* ## Bounded, and it says when the bound bit
|
|
87
|
+
*
|
|
88
|
+
* The log is append-only and unbounded by nature, so the read is capped — and a cap that silently
|
|
89
|
+
* truncates is the failure mode, not the bound. `truncated` says the cap was reached, the same word
|
|
90
|
+
* `@pithy-sh/auth`'s bounded sub-lists use. A caller counting rows must read it; a caller asking only
|
|
91
|
+
* "did anything go out" may ignore it, because a truncated page is still a non-empty one.
|
|
92
|
+
*/
|
|
93
|
+
/**
|
|
94
|
+
* One job as the send-decision reader sees it: the handle, the outcome, and the two instants.
|
|
95
|
+
*
|
|
96
|
+
* Derived from `EmailJob` with `.pick()` rather than restated, so the codecs and the field descriptions
|
|
97
|
+
* come from the one table definition and a column added to the row does not silently appear here.
|
|
98
|
+
* Re-described because `.pick()` builds a new schema and the top-level description does not follow it.
|
|
99
|
+
*/
|
|
100
|
+
const SentSummary = EmailJob.pick({
|
|
101
|
+
id: true,
|
|
102
|
+
status: true,
|
|
103
|
+
createdAt: true,
|
|
104
|
+
sentAt: true
|
|
105
|
+
}).describe("One previously enqueued message, as the caller deciding whether to send another one sees it. No recipient, no subject, no payload, no provider text — the id is the handle into the full record for anyone holding the scope to read it.");
|
|
106
|
+
/**
|
|
107
|
+
* Every job matching one subject since an instant, newest first.
|
|
108
|
+
*
|
|
109
|
+
* The subject is `(to, template)`, or a `correlation`, or both — see {@link SentSubject}. Neither is not
|
|
110
|
+
* a subject, and the type will not build one.
|
|
111
|
+
*
|
|
112
|
+
* **A row that will not parse throws.** It is tempting to skip it and carry on, and it is wrong here in
|
|
113
|
+
* a way it is not on a listing: this reader's answer decides whether a message goes out. A skipped row
|
|
114
|
+
* is reported as an email that never went, which means a duplicate send — or, where the caller is
|
|
115
|
+
* looking for who to send a *correction* to, a correction withheld from exactly the person owed one.
|
|
116
|
+
* Both failures are silent and neither is recoverable after the fact, so a row this schema cannot read
|
|
117
|
+
* stops the decision instead of quietly biasing it.
|
|
118
|
+
*/
|
|
119
|
+
async function sentSince(db, filter) {
|
|
120
|
+
const limit = pageLimit(filter.limit);
|
|
121
|
+
let query = db.selectFrom("pithyEmailJobs").select([
|
|
122
|
+
"id",
|
|
123
|
+
"status",
|
|
124
|
+
"createdAt",
|
|
125
|
+
"sentAt"
|
|
126
|
+
]).where("createdAt", ">=", filter.since.getTime()).orderBy("createdAt", "desc").orderBy("id", "desc").limit(limit + 1);
|
|
127
|
+
if (filter.to !== void 0) query = query.where("recipientKey", "=", normalizeAddress(filter.to));
|
|
128
|
+
if (filter.template !== void 0) query = query.where("template", "=", filter.template);
|
|
129
|
+
if (filter.correlation !== void 0) query = query.where("correlation", "=", filter.correlation);
|
|
130
|
+
const rows = await query.execute();
|
|
131
|
+
return {
|
|
132
|
+
items: rows.slice(0, limit).map((row) => {
|
|
133
|
+
const parsed = SentSummary.safeParse(row);
|
|
134
|
+
if (!parsed.success) throw new InternalError({
|
|
135
|
+
message: "The send log could not be read.",
|
|
136
|
+
action: "Inspect pithy_email_jobs for a row this deployment's schema cannot decode.",
|
|
137
|
+
detail: `pithy_email_jobs row '${String(row.id)}' does not satisfy EmailJob: ${parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.code}`).join("; ")}`
|
|
138
|
+
});
|
|
139
|
+
return parsed.data;
|
|
140
|
+
}),
|
|
141
|
+
truncated: rows.length > limit
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
//#endregion
|
|
145
|
+
export { SentSummary, getJob, listJobs, sentSince };
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { EmailJob } from "../data/emailJob";
|
|
4
|
+
import type { EmailDatabase, EmailSuppressionDatabase } from "../data/tables";
|
|
5
|
+
import type { SendWorkflowBinding } from "../send/enqueue";
|
|
6
|
+
/**
|
|
7
|
+
* Putting a failed job back in the queue — the body behind `POST /email/jobs/:id/retry`.
|
|
8
|
+
*
|
|
9
|
+
* ## A handler never sends
|
|
10
|
+
*
|
|
11
|
+
* `runSend` is Workflow-only and is never called from here. A retry does what `enqueueEmail` does: it
|
|
12
|
+
* puts the row back into a sendable state and dispatches the send Workflow. That keeps the one place
|
|
13
|
+
* that talks to the Email Service inside a durable step with retries and history, which is the whole
|
|
14
|
+
* reason email is a job table rather than a function call.
|
|
15
|
+
*
|
|
16
|
+
* A failed dispatch is safe and deliberately swallowed. The row is `pending` before the Workflow is
|
|
17
|
+
* started, so the every-minute scheduler's safety net re-drives it on the next tick — the same contract
|
|
18
|
+
* `enqueueEmail` relies on. Losing the dispatch costs a minute; failing the request after the row was
|
|
19
|
+
* already reset would tell an operator nothing happened when something did.
|
|
20
|
+
*
|
|
21
|
+
* ## Only a `failed` job may be retried
|
|
22
|
+
*
|
|
23
|
+
* Every other state is refused with `core/conflict`, and each refusal is a different thing going wrong:
|
|
24
|
+
*
|
|
25
|
+
* - `sent` — already delivered. Retrying is a duplicate email to a real person. It is also the one
|
|
26
|
+
* state whose inputs are gone: a transactional job's payload is dropped when the message goes out,
|
|
27
|
+
* which is safe precisely because this refusal is what makes `sent` terminal.
|
|
28
|
+
* - `pending` / `scheduled` / `sending` — still in flight. Resetting it races the scheduler, and
|
|
29
|
+
* `sending` in particular is a job a Workflow is holding right now.
|
|
30
|
+
* - `suppressed` — the address is on the block list. Retrying is the one send this capability must
|
|
31
|
+
* never make.
|
|
32
|
+
* - `bounced` — the recipient's server said permanently no, and the bounce handler only sets this
|
|
33
|
+
* state while suppressing the address, so a retry is the previous case wearing a different label.
|
|
34
|
+
* - `canceled` — somebody withdrew it. Reviving a withdrawal is a separate decision, not a retry, and
|
|
35
|
+
* it should have to be made somewhere it is named.
|
|
36
|
+
*
|
|
37
|
+
* ## The attempt budget is reset, and it has to be
|
|
38
|
+
*
|
|
39
|
+
* `runSend` gives up when `attempts >= maxAttempts`. A job that failed did so having spent its budget,
|
|
40
|
+
* so a retry that left `attempts` alone would take one retryable error to fail terminally again — the
|
|
41
|
+
* button would appear to work and change nothing. `attempts` returns to zero; `error` does not, because
|
|
42
|
+
* it is the record of what went wrong last time and a successful send clears it anyway.
|
|
43
|
+
*
|
|
44
|
+
* ## The batch id is re-minted, and the old one must not survive
|
|
45
|
+
*
|
|
46
|
+
* A `failed` row still names the batch that failed it (pithy-sh/pithy#342), and that id is about to
|
|
47
|
+
* become wrong in both directions at once. `batchId` means *the instance coming for this row* — see
|
|
48
|
+
* `send/batchIdentity.ts` — and after a retry the instance coming for it is the one this function
|
|
49
|
+
* starts, not the one that gave up on it.
|
|
50
|
+
*
|
|
51
|
+
* Leaving the old id there is not a stale label. It hands the scheduler's veto the wrong Workflow to ask
|
|
52
|
+
* about, and a failure inside a batch is exactly the case where that Workflow is *still running*: a
|
|
53
|
+
* batch of fifty that failed job seven walks on to job fifty. So the tick that should re-drive the retry
|
|
54
|
+
* asks about the batch that abandoned it, is told "alive", and holds — the operator's click sends
|
|
55
|
+
* nothing for as long as the old batch runs. Then the old batch ends, the same row reads as stranded,
|
|
56
|
+
* and the tick starts a second Workflow behind the one this function already started. Held when it
|
|
57
|
+
* should send, then sent twice: one wrong id, both failures.
|
|
58
|
+
*
|
|
59
|
+
* So a retry mints its own, writes it in the same statement that makes the row queryable again, and
|
|
60
|
+
* creates the instance under it. Null when there is no binding to dispatch on, because then nothing is
|
|
61
|
+
* coming for the row and the scheduler should claim it on the next tick — and the row is `undispatched`
|
|
62
|
+
* rather than `pending` there, for the reason the write itself states.
|
|
63
|
+
*/
|
|
64
|
+
/** What a retry needs: both databases, the send Workflow binding, and the clock. */
|
|
65
|
+
export interface RetryDeps {
|
|
66
|
+
/** The per-environment jobs database. */
|
|
67
|
+
db: EmailDatabase;
|
|
68
|
+
/** The global suppression database — checked before the row is touched. */
|
|
69
|
+
suppressionDb: EmailSuppressionDatabase;
|
|
70
|
+
/**
|
|
71
|
+
* The send Workflow binding. Optional so a Worker that somehow lacks it still resets the row and
|
|
72
|
+
* leaves the scheduler to re-drive, rather than failing an operator's click outright.
|
|
73
|
+
*/
|
|
74
|
+
sender?: SendWorkflowBinding;
|
|
75
|
+
now: Date;
|
|
76
|
+
/**
|
|
77
|
+
* Mint the id of the batch this retry dispatches — **the send Workflow instance's id**
|
|
78
|
+
* (pithy-sh/pithy#342). Defaults to {@link mintBatchId}; injected only so a test can name it.
|
|
79
|
+
*/
|
|
80
|
+
newBatchId?: () => string;
|
|
81
|
+
}
|
|
82
|
+
/** What a retry did. */
|
|
83
|
+
export interface RetryResult {
|
|
84
|
+
/** The job that was re-queued. */
|
|
85
|
+
job: EmailJob;
|
|
86
|
+
/**
|
|
87
|
+
* Whether the send Workflow actually started. False means the scheduler will pick the row up within
|
|
88
|
+
* the minute — the mail is not lost, it is merely not immediate.
|
|
89
|
+
*/
|
|
90
|
+
dispatched: boolean;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Re-queue one failed job.
|
|
94
|
+
*
|
|
95
|
+
* Reads before it writes: the job must exist, be `failed`, and its recipient must not have been
|
|
96
|
+
* suppressed in the meantime. That last check is not redundant with `runSend`'s — `runSend` would mark
|
|
97
|
+
* the row `suppressed` and skip, which reports to the operator as a successful retry that silently sent
|
|
98
|
+
* nothing. Refusing here says what actually happened.
|
|
99
|
+
*/
|
|
100
|
+
export declare function retryJob(deps: RetryDeps, jobId: string): Promise<RetryResult>;
|
|
101
|
+
//# sourceMappingURL=retry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/jobs/retry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAK3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,EAAE,EAAE,aAAa,CAAC;IAClB,2EAA2E;IAC3E,aAAa,EAAE,wBAAwB,CAAC;IACxC;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,GAAG,EAAE,IAAI,CAAC;IACV;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC;CAC3B;AAED,wBAAwB;AACxB,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,GAAG,EAAE,QAAQ,CAAC;IACd;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAqGnF"}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { blockingSuppression } from "../send/suppression.js";
|
|
4
|
+
import { EmailSuppressedError } from "../error/errors.js";
|
|
5
|
+
import { templateKind } from "../templates/engine.js";
|
|
6
|
+
import { getJob } from "./read.js";
|
|
7
|
+
import { mintBatchId } from "../send/batchIdentity.js";
|
|
8
|
+
import { ConflictError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
|
|
9
|
+
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
10
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
11
|
+
//#region src/jobs/retry.ts
|
|
12
|
+
/**
|
|
13
|
+
* Re-queue one failed job.
|
|
14
|
+
*
|
|
15
|
+
* Reads before it writes: the job must exist, be `failed`, and its recipient must not have been
|
|
16
|
+
* suppressed in the meantime. That last check is not redundant with `runSend`'s — `runSend` would mark
|
|
17
|
+
* the row `suppressed` and skip, which reports to the operator as a successful retry that silently sent
|
|
18
|
+
* nothing. Refusing here says what actually happened.
|
|
19
|
+
*/
|
|
20
|
+
async function retryJob(deps, jobId) {
|
|
21
|
+
const existing = await getJob(deps.db, jobId);
|
|
22
|
+
if (!existing) throw new NotFoundError({
|
|
23
|
+
message: "No such email job.",
|
|
24
|
+
action: "Check the job id against the send log.",
|
|
25
|
+
detail: `email job '${jobId}' not found`
|
|
26
|
+
});
|
|
27
|
+
if (existing.status !== "failed") throw new ConflictError({
|
|
28
|
+
message: `Only a failed job can be retried. This one is ${existing.status}.`,
|
|
29
|
+
action: "Retry a job whose status is failed.",
|
|
30
|
+
detail: `email job '${jobId}' is ${existing.status}`
|
|
31
|
+
});
|
|
32
|
+
const recipient = normalizeAddress(existing.toAddress);
|
|
33
|
+
const blocked = await blockingSuppression(deps.suppressionDb, recipient, deps.now, templateKind(existing.template));
|
|
34
|
+
if (blocked) throw new EmailSuppressedError({
|
|
35
|
+
message: `That recipient is on the suppression list (${blocked}), so this job cannot be retried.`,
|
|
36
|
+
action: "Remove the address from the suppression list first, if that is what you mean to do.",
|
|
37
|
+
detail: `recipient of email job '${jobId}' is suppressed: ${blocked}`
|
|
38
|
+
});
|
|
39
|
+
const batchId = deps.sender ? (deps.newBatchId ?? mintBatchId)() : null;
|
|
40
|
+
if (((await deps.db.updateTable("pithyEmailJobs").set({
|
|
41
|
+
batchId,
|
|
42
|
+
status: deps.sender ? "pending" : "undispatched",
|
|
43
|
+
sendAt: SQLiteDate.encode(deps.now),
|
|
44
|
+
attempts: 0,
|
|
45
|
+
updatedAt: SQLiteDate.encode(deps.now),
|
|
46
|
+
createdAt: SQLiteDate.encode(deps.now)
|
|
47
|
+
}).where("id", "=", jobId).where("status", "=", "failed").executeTakeFirst()).numUpdatedRows ?? 0n) === 0n) {
|
|
48
|
+
const current = await getJob(deps.db, jobId);
|
|
49
|
+
throw new ConflictError({
|
|
50
|
+
message: `Only a failed job can be retried. This one is ${current?.status ?? "no longer there"}.`,
|
|
51
|
+
action: "Reload the send log — somebody may have retried it already.",
|
|
52
|
+
detail: `email job '${jobId}' left the failed state between the read and the write`
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
let dispatched = false;
|
|
56
|
+
if (deps.sender && batchId) try {
|
|
57
|
+
await deps.sender.create({
|
|
58
|
+
id: batchId,
|
|
59
|
+
params: { jobIds: [jobId] }
|
|
60
|
+
});
|
|
61
|
+
dispatched = true;
|
|
62
|
+
} catch {}
|
|
63
|
+
return {
|
|
64
|
+
job: await getJob(deps.db, jobId) ?? existing,
|
|
65
|
+
dispatched
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
//#endregion
|
|
69
|
+
export { retryJob };
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { Migration } from "kysely/migration";
|
|
4
|
+
/**
|
|
5
|
+
* Create the per-environment email tables in the app database: `pithy_email_jobs` and
|
|
6
|
+
* `pithy_email_events`. Both carry the `pithy_email_` prefix so they never clash with an adopter's own
|
|
7
|
+
* tables. (Suppression lives in its own durable database — see `0001_suppressions.ts`.)
|
|
8
|
+
*
|
|
9
|
+
* Identifiers are declared in **camelCase**: the runner installs `CamelCasePlugin`, which snake-cases
|
|
10
|
+
* every identifier in the emitted DDL (CLAUDE.md §Data layer). `down` is the tested inverse — indexes
|
|
11
|
+
* then tables, in reverse creation order (D1 has no transactional DDL).
|
|
12
|
+
*
|
|
13
|
+
* **This is the capability's whole schema for this database, in one migration, and that is the rule
|
|
14
|
+
* while nothing is published.** CONTRIBUTING.md §Migrations states it and
|
|
15
|
+
* `packages/cli/src/migrations/oneMigration.test.ts` enforces it: a chain buys exactly one thing —
|
|
16
|
+
* walking a database that already holds rows from an old shape to a new one — and there is no such
|
|
17
|
+
* database, so a `0002` would be a step from a shape that never ran to a shape that never shipped.
|
|
18
|
+
*
|
|
19
|
+
* **Amended in place on 2026-08-23** for `locale` (pithy-sh/pithy#441), and **on 2026-08-16** for
|
|
20
|
+
* `correlation` (pithy-sh/pithy#382). The condition was re-checked on each occasion rather than
|
|
21
|
+
* assumed, because CONTRIBUTING.md asks a later reader to check it:
|
|
22
|
+
*
|
|
23
|
+
* - `@pithy-sh/email` is at `0.0.0` and `npm view @pithy-sh/email version` is a 404. Nothing has been
|
|
24
|
+
* released, so no `0200_email_0001_init` has run anywhere a chain would be replayed against.
|
|
25
|
+
* - The only adopter is `pithy-sh/dashboard`, and `GET /accounts/602df2e6ce74e98b4c7ac5e90a3af5c8/d1/database`
|
|
26
|
+
* — the account `apps/board/pithy.config.ts` pins, not whatever wrangler is logged in to — returns an
|
|
27
|
+
* **empty list**. There is no deployed D1 at all, so none holds a `pithy_email_jobs` row.
|
|
28
|
+
*
|
|
29
|
+
* **The moment either stops being true this file is history, and the chain is append-only.** A version
|
|
30
|
+
* cut, or one database on that account, and the next column is a `0002`. Nothing about a tidy `0001`
|
|
31
|
+
* tells a reader which side of that line they are on — re-run the two checks, do not infer them.
|
|
32
|
+
*/
|
|
33
|
+
export declare const email_0001_init: Migration;
|
|
34
|
+
//# sourceMappingURL=0001_init.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"0001_init.d.ts","sourceRoot":"","sources":["../../src/migrations/0001_init.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,EAAE,SA0I7B,CAAC"}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
//#region src/migrations/0001_init.ts
|
|
4
|
+
/**
|
|
5
|
+
* Create the per-environment email tables in the app database: `pithy_email_jobs` and
|
|
6
|
+
* `pithy_email_events`. Both carry the `pithy_email_` prefix so they never clash with an adopter's own
|
|
7
|
+
* tables. (Suppression lives in its own durable database — see `0001_suppressions.ts`.)
|
|
8
|
+
*
|
|
9
|
+
* Identifiers are declared in **camelCase**: the runner installs `CamelCasePlugin`, which snake-cases
|
|
10
|
+
* every identifier in the emitted DDL (CLAUDE.md §Data layer). `down` is the tested inverse — indexes
|
|
11
|
+
* then tables, in reverse creation order (D1 has no transactional DDL).
|
|
12
|
+
*
|
|
13
|
+
* **This is the capability's whole schema for this database, in one migration, and that is the rule
|
|
14
|
+
* while nothing is published.** CONTRIBUTING.md §Migrations states it and
|
|
15
|
+
* `packages/cli/src/migrations/oneMigration.test.ts` enforces it: a chain buys exactly one thing —
|
|
16
|
+
* walking a database that already holds rows from an old shape to a new one — and there is no such
|
|
17
|
+
* database, so a `0002` would be a step from a shape that never ran to a shape that never shipped.
|
|
18
|
+
*
|
|
19
|
+
* **Amended in place on 2026-08-23** for `locale` (pithy-sh/pithy#441), and **on 2026-08-16** for
|
|
20
|
+
* `correlation` (pithy-sh/pithy#382). The condition was re-checked on each occasion rather than
|
|
21
|
+
* assumed, because CONTRIBUTING.md asks a later reader to check it:
|
|
22
|
+
*
|
|
23
|
+
* - `@pithy-sh/email` is at `0.0.0` and `npm view @pithy-sh/email version` is a 404. Nothing has been
|
|
24
|
+
* released, so no `0200_email_0001_init` has run anywhere a chain would be replayed against.
|
|
25
|
+
* - The only adopter is `pithy-sh/dashboard`, and `GET /accounts/602df2e6ce74e98b4c7ac5e90a3af5c8/d1/database`
|
|
26
|
+
* — the account `apps/board/pithy.config.ts` pins, not whatever wrangler is logged in to — returns an
|
|
27
|
+
* **empty list**. There is no deployed D1 at all, so none holds a `pithy_email_jobs` row.
|
|
28
|
+
*
|
|
29
|
+
* **The moment either stops being true this file is history, and the chain is append-only.** A version
|
|
30
|
+
* cut, or one database on that account, and the next column is a `0002`. Nothing about a tidy `0001`
|
|
31
|
+
* tells a reader which side of that line they are on — re-run the two checks, do not infer them.
|
|
32
|
+
*/
|
|
33
|
+
const email_0001_init = {
|
|
34
|
+
up: async (db) => {
|
|
35
|
+
await db.schema.createTable("pithyEmailJobs").addColumn("id", "text", (c) => c.primaryKey()).addColumn("toAddress", "text", (c) => c.notNull()).addColumn("recipientKey", "text", (c) => c.notNull()).addColumn("fromAddress", "text", (c) => c.notNull()).addColumn("fromName", "text", (c) => c.notNull()).addColumn("subject", "text", (c) => c.notNull()).addColumn("template", "text", (c) => c.notNull()).addColumn("category", "text", (c) => c.notNull()).addColumn("payload", "text", (c) => c.notNull()).addColumn("payloadRedactedAt", "integer").addColumn("status", "text", (c) => c.notNull()).addColumn("mode", "text", (c) => c.notNull()).addColumn("attempts", "integer", (c) => c.notNull().defaultTo(0)).addColumn("batchId", "text").addColumn("sendAt", "integer", (c) => c.notNull()).addColumn("timezone", "text").addColumn("localTime", "text").addColumn("campaignId", "text").addColumn("locale", "text").addColumn("correlation", "text").addColumn("openTracking", "integer", (c) => c.notNull().defaultTo(0)).addColumn("clickTracking", "integer", (c) => c.notNull().defaultTo(0)).addColumn("messageId", "text").addColumn("error", "text").addColumn("bounceCode", "text").addColumn("bounceType", "text").addColumn("replyTo", "text").addColumn("inReplyTo", "text").addColumn("references", "text").addColumn("createdAt", "integer", (c) => c.notNull()).addColumn("updatedAt", "integer", (c) => c.notNull()).addColumn("sentAt", "integer").execute();
|
|
36
|
+
await db.schema.createIndex("pithyEmailJobsDueIdx").on("pithyEmailJobs").columns(["status", "sendAt"]).execute();
|
|
37
|
+
await db.schema.createIndex("pithyEmailJobsMessageIdIdx").on("pithyEmailJobs").column("messageId").execute();
|
|
38
|
+
await db.schema.createTable("pithyEmailEvents").addColumn("id", "integer", (c) => c.primaryKey().autoIncrement()).addColumn("jobId", "text", (c) => c.notNull()).addColumn("recipient", "text", (c) => c.notNull()).addColumn("type", "text", (c) => c.notNull()).addColumn("linkLabel", "text").addColumn("linkUrl", "text").addColumn("campaignId", "text").addColumn("detail", "text").addColumn("createdAt", "integer", (c) => c.notNull()).execute();
|
|
39
|
+
await db.schema.createIndex("pithyEmailEventsJobIdIdx").on("pithyEmailEvents").column("jobId").execute();
|
|
40
|
+
await db.schema.createIndex("pithyEmailJobsStatusCreatedIdx").on("pithyEmailJobs").columns(["status", "createdAt"]).execute();
|
|
41
|
+
await db.schema.createIndex("pithyEmailJobsCreatedIdx").on("pithyEmailJobs").column("createdAt").execute();
|
|
42
|
+
await db.schema.createIndex("pithyEmailJobsRecipientTemplateIdx").on("pithyEmailJobs").columns([
|
|
43
|
+
"recipientKey",
|
|
44
|
+
"template",
|
|
45
|
+
"createdAt"
|
|
46
|
+
]).execute();
|
|
47
|
+
await db.schema.createIndex("pithyEmailJobsCorrelationIdx").on("pithyEmailJobs").columns(["correlation", "createdAt"]).execute();
|
|
48
|
+
},
|
|
49
|
+
down: async (db) => {
|
|
50
|
+
await db.schema.dropIndex("pithyEmailJobsCorrelationIdx").execute();
|
|
51
|
+
await db.schema.dropIndex("pithyEmailJobsRecipientTemplateIdx").execute();
|
|
52
|
+
await db.schema.dropIndex("pithyEmailJobsCreatedIdx").execute();
|
|
53
|
+
await db.schema.dropIndex("pithyEmailJobsStatusCreatedIdx").execute();
|
|
54
|
+
await db.schema.dropIndex("pithyEmailEventsJobIdIdx").execute();
|
|
55
|
+
await db.schema.dropTable("pithyEmailEvents").execute();
|
|
56
|
+
await db.schema.dropIndex("pithyEmailJobsMessageIdIdx").execute();
|
|
57
|
+
await db.schema.dropIndex("pithyEmailJobsDueIdx").execute();
|
|
58
|
+
await db.schema.dropTable("pithyEmailJobs").execute();
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
//#endregion
|
|
62
|
+
export { email_0001_init };
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { Migration } from "kysely/migration";
|
|
4
|
+
/**
|
|
5
|
+
* Create the global suppression table in the dedicated, durable `EMAIL_SUPPRESSIONS` database —
|
|
6
|
+
* distinct from the per-environment app `DB`, because an address that hard-bounced, complained, or
|
|
7
|
+
* unsubscribed must never be emailed from *any* environment. Mirrors the shared-DB pattern of
|
|
8
|
+
* `@pithy-sh/secrets`. The single inbound bounce worker and the unsubscribe callbacks write it; every
|
|
9
|
+
* environment's send path reads it.
|
|
10
|
+
*/
|
|
11
|
+
export declare const email_0001_suppressions: Migration;
|
|
12
|
+
//# sourceMappingURL=0001_suppressions.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"0001_suppressions.d.ts","sourceRoot":"","sources":["../../src/migrations/0001_suppressions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,SA0BrC,CAAC"}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
//#region src/migrations/0001_suppressions.ts
|
|
4
|
+
/**
|
|
5
|
+
* Create the global suppression table in the dedicated, durable `EMAIL_SUPPRESSIONS` database —
|
|
6
|
+
* distinct from the per-environment app `DB`, because an address that hard-bounced, complained, or
|
|
7
|
+
* unsubscribed must never be emailed from *any* environment. Mirrors the shared-DB pattern of
|
|
8
|
+
* `@pithy-sh/secrets`. The single inbound bounce worker and the unsubscribe callbacks write it; every
|
|
9
|
+
* environment's send path reads it.
|
|
10
|
+
*/
|
|
11
|
+
const email_0001_suppressions = {
|
|
12
|
+
up: async (db) => {
|
|
13
|
+
await db.schema.createTable("pithyEmailSuppressions").addColumn("id", "integer", (c) => c.primaryKey().autoIncrement()).addColumn("email", "text", (c) => c.notNull().unique()).addColumn("reason", "text", (c) => c.notNull()).addColumn("jobId", "text").addColumn("environment", "text").addColumn("detail", "text").addColumn("createdAt", "integer", (c) => c.notNull()).addColumn("expiresAt", "integer").execute();
|
|
14
|
+
await db.schema.createIndex("pithyEmailSuppressionsCreatedIdx").on("pithyEmailSuppressions").column("createdAt").execute();
|
|
15
|
+
},
|
|
16
|
+
down: async (db) => {
|
|
17
|
+
await db.schema.dropIndex("pithyEmailSuppressionsCreatedIdx").execute();
|
|
18
|
+
await db.schema.dropTable("pithyEmailSuppressions").execute();
|
|
19
|
+
}
|
|
20
|
+
};
|
|
21
|
+
//#endregion
|
|
22
|
+
export { email_0001_suppressions };
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
/**
|
|
5
|
+
* How mail leaves the email host worker when that worker is running on a developer's machine.
|
|
6
|
+
*
|
|
7
|
+
* The point of the local loop is a magic link that **arrives** (pithy-sh/pithy#410). Until now it
|
|
8
|
+
* could not: `pithy dev` never ran the email host at all, so a sign-in wrote a row that said
|
|
9
|
+
* `pending` and a screen that said "check your inbox". With the host in the dev set, one flag decides
|
|
10
|
+
* what its `send_email` binding does — and the default is the one that ends the loop.
|
|
11
|
+
*
|
|
12
|
+
* Both settings run the Worker locally. Neither is a transport of ours: `wrangler dev` implements the
|
|
13
|
+
* binding either way, and there is no REST or SMTP sender in this kit (that stays out of scope until
|
|
14
|
+
* a context with no binding at all needs one).
|
|
15
|
+
*/
|
|
16
|
+
/** What the host's `send_email` binding does under `pithy dev`. */
|
|
17
|
+
export declare const DevMailDelivery: z.ZodEnum<{
|
|
18
|
+
remote: "remote";
|
|
19
|
+
simulator: "simulator";
|
|
20
|
+
}>;
|
|
21
|
+
export type DevMailDelivery = z.infer<typeof DevMailDelivery>;
|
|
22
|
+
/**
|
|
23
|
+
* Which bindings the resolved host config must mark `remote: true`, for one environment.
|
|
24
|
+
*
|
|
25
|
+
* The committed template no longer hardcodes the flag, because a hardcoded `true` cannot be turned
|
|
26
|
+
* off: `resolveWorkflowHost` only ever *adds* `remote`, so a template that already carried it left no
|
|
27
|
+
* way to select the simulator. The decision moved here, where the capability's config can reach it.
|
|
28
|
+
*
|
|
29
|
+
* Outside `dev` the answer is always `remote: true`. A deployed Worker ignores the flag entirely —
|
|
30
|
+
* it is a `wrangler dev` instruction — so the resolved config for `staging` and `prod` is byte-
|
|
31
|
+
* identical whatever an adopter chose for their laptop.
|
|
32
|
+
*/
|
|
33
|
+
export declare function emailRemoteBindings(env: string, delivery: DevMailDelivery): readonly string[];
|
|
34
|
+
//# sourceMappingURL=devDelivery.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"devDelivery.d.ts","sourceRoot":"","sources":["../../src/provision/devDelivery.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AAEH,mEAAmE;AACnE,eAAO,MAAM,eAAe;;;EAIzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAQ9D;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CAG7F"}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
//#region src/provision/devDelivery.ts
|
|
5
|
+
/**
|
|
6
|
+
* How mail leaves the email host worker when that worker is running on a developer's machine.
|
|
7
|
+
*
|
|
8
|
+
* The point of the local loop is a magic link that **arrives** (pithy-sh/pithy#410). Until now it
|
|
9
|
+
* could not: `pithy dev` never ran the email host at all, so a sign-in wrote a row that said
|
|
10
|
+
* `pending` and a screen that said "check your inbox". With the host in the dev set, one flag decides
|
|
11
|
+
* what its `send_email` binding does — and the default is the one that ends the loop.
|
|
12
|
+
*
|
|
13
|
+
* Both settings run the Worker locally. Neither is a transport of ours: `wrangler dev` implements the
|
|
14
|
+
* binding either way, and there is no REST or SMTP sender in this kit (that stays out of scope until
|
|
15
|
+
* a context with no binding at all needs one).
|
|
16
|
+
*/
|
|
17
|
+
/** What the host's `send_email` binding does under `pithy dev`. */
|
|
18
|
+
const DevMailDelivery = z.enum(["remote", "simulator"]).describe("How email is delivered when the host worker runs under `pithy dev`. **`remote` is the default, and it sends real mail from the developer's machine** — `remote: true` on the `send_email` binding runs the Worker locally and delivers through Cloudflare Email Service, so the message lands in a real inbox with the same DKIM and the same delivery logs as production. It needs a Cloudflare login `wrangler dev` can use and a sending domain already onboarded onto Email Service. `simulator` sends nothing: `wrangler dev` logs the sender, recipient and subject and writes the rendered HTML and text bodies to disk, which is what an offline machine and CI want. Choose `simulator` deliberately — the cost of `remote` is that a test sign-in really does reach whatever address it was given.");
|
|
19
|
+
/** The local environment. The only one this flag governs; every other one deploys and delivers for real. */
|
|
20
|
+
const DEV_ENVIRONMENT = "dev";
|
|
21
|
+
/** The `send_email` binding name the committed host template declares. */
|
|
22
|
+
const SEND_BINDING = "EMAIL";
|
|
23
|
+
/**
|
|
24
|
+
* Which bindings the resolved host config must mark `remote: true`, for one environment.
|
|
25
|
+
*
|
|
26
|
+
* The committed template no longer hardcodes the flag, because a hardcoded `true` cannot be turned
|
|
27
|
+
* off: `resolveWorkflowHost` only ever *adds* `remote`, so a template that already carried it left no
|
|
28
|
+
* way to select the simulator. The decision moved here, where the capability's config can reach it.
|
|
29
|
+
*
|
|
30
|
+
* Outside `dev` the answer is always `remote: true`. A deployed Worker ignores the flag entirely —
|
|
31
|
+
* it is a `wrangler dev` instruction — so the resolved config for `staging` and `prod` is byte-
|
|
32
|
+
* identical whatever an adopter chose for their laptop.
|
|
33
|
+
*/
|
|
34
|
+
function emailRemoteBindings(env, delivery) {
|
|
35
|
+
if (env === DEV_ENVIRONMENT && delivery === "simulator") return [];
|
|
36
|
+
return [SEND_BINDING];
|
|
37
|
+
}
|
|
38
|
+
//#endregion
|
|
39
|
+
export { DevMailDelivery, emailRemoteBindings };
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
|
|
4
|
+
import { type EmailMessageLayers } from "../templates/messages";
|
|
5
|
+
/**
|
|
6
|
+
* Flatten a composed project's layers into the `EMAIL_MESSAGES` var's value, one catalog per locale.
|
|
7
|
+
*
|
|
8
|
+
* `locales` is the project's `supportedLocales`; a project that composed no i18n capability passes
|
|
9
|
+
* none, gets `{}`, and deploys a host with no var at all — which is the same English it always sent.
|
|
10
|
+
*/
|
|
11
|
+
export declare function emailHostCatalogs(locales: readonly string[], layersFor: EmailMessageLayers): LocaleCatalogs;
|
|
12
|
+
//# sourceMappingURL=hostCatalogs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"hostCatalogs.d.ts","sourceRoot":"","sources":["../../src/provision/hostCatalogs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AA6DhF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,kBAAkB,GAAG,cAAc,CAkC3G"}
|