@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,64 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { EmailJobStatus, SendMode, TemplateCategory } from "./enums.js";
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
import { SQLiteBoolean, SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
|
|
6
|
+
import { Locale } from "@pithy-sh/core/src/i18n/locale";
|
|
7
|
+
//#region src/data/emailJob.ts
|
|
8
|
+
/**
|
|
9
|
+
* The template input variables, stored as a JSON column. The per-template Zod payload schema
|
|
10
|
+
* validates these before a job is enqueued; the row keeps the validated object so the send Workflow
|
|
11
|
+
* can re-render without the caller present. A bag of strings/unknowns at the row level — the template
|
|
12
|
+
* id plus this payload reconstruct the email.
|
|
13
|
+
*/
|
|
14
|
+
const EmailJobPayload = z.record(z.string(), z.unknown()).describe("The validated template input variables for this job, re-rendered by the send Workflow. Empty once `payloadRedactedAt` is set — a transactional job's inputs are dropped when the message goes out.");
|
|
15
|
+
/**
|
|
16
|
+
* What the `payload` column holds once a job's inputs are spent.
|
|
17
|
+
*
|
|
18
|
+
* An empty object, encoded through the same codec every other write uses rather than written as a
|
|
19
|
+
* `"{}"` literal — a column this schema could not read back would turn a delivered job into a row that
|
|
20
|
+
* throws when an operator opens it. The fact that it *was* redacted is `payloadRedactedAt`; this is
|
|
21
|
+
* only what is left where the variables were.
|
|
22
|
+
*/
|
|
23
|
+
const SPENT_PAYLOAD = sqliteJson(EmailJobPayload).encode({});
|
|
24
|
+
/**
|
|
25
|
+
* One row in `pithy_email_jobs` — the spine of the capability. Every email is a row first: a request
|
|
26
|
+
* handler only ever enqueues one, and the actual send always runs inside a Workflow. `z.output` is the
|
|
27
|
+
* app shape (Dates, booleans); `z.input` is the SQLite row (ms-epoch, 0|1, JSON string).
|
|
28
|
+
*/
|
|
29
|
+
const EmailJob = z.object({
|
|
30
|
+
id: z.string().describe("UUID primary key. Text, not autoincrement, so a job id embedded in a tracking link cannot be enumerated."),
|
|
31
|
+
toAddress: z.string().describe("The recipient's email address. Lowercased and checked against the suppression list before sending."),
|
|
32
|
+
recipientKey: z.string().describe("The recipient under `normalizeAddress` — the one form every comparison in the kit is against, and the only column anything matches a recipient on. `toAddress` deliberately keeps what the caller typed, because an operator diagnosing a send needs to see the string that was actually addressed; that makes it useless as a key, since `Ada@example.com` and `ada@example.com` are one mailbox and two rows. Doing the folding in SQL instead would not work: SQLite's `lower()` is ASCII-only while `normalizeAddress` is `toLowerCase()`, so the two disagree on exactly the addresses nobody tests with. The same value `pithy_email_events.recipient` is keyed on, so a job and its events agree on who the person is."),
|
|
33
|
+
fromAddress: z.string().describe("The sender address. Must use a domain onboarded onto Cloudflare Email Service."),
|
|
34
|
+
fromName: z.string().describe("The sender display name recipients see in their inbox."),
|
|
35
|
+
subject: z.string().describe("The rendered subject line."),
|
|
36
|
+
template: z.string().describe("The template id (e.g. `magicLink`, `newsletter`) used to render this email."),
|
|
37
|
+
category: TemplateCategory.describe("The template's category — drives unsubscribe enforcement and tracking defaults."),
|
|
38
|
+
payload: sqliteJson(EmailJobPayload).describe("The validated template input variables, as a JSON column. Emptied when the message is delivered, for every template whose category is `transactional` — see `payloadRedactedAt`."),
|
|
39
|
+
payloadRedactedAt: SQLiteDate.nullish().describe("When this job's inputs were dropped, or null while it still holds them. A magic link's payload *is* the sign-in link, so keeping it after delivery is a second, permanent copy of a credential in a table nobody thinks of as holding secrets. Null and an empty payload mean different things — the first is a job enqueued with no variables, the second is one whose variables were spent — which is why this is a timestamp and not the absence of data."),
|
|
40
|
+
status: EmailJobStatus.describe("The job's lifecycle state."),
|
|
41
|
+
mode: SendMode.describe("How this job's send time was determined."),
|
|
42
|
+
attempts: z.number().int().describe("How many send attempts have been made; incremented on each Workflow try."),
|
|
43
|
+
batchId: z.string().nullish().describe("The send batch holding this job — the id of the send Workflow instance dispatched for it, minted by whoever claimed it. Null for a job nothing has claimed. This *is* the claim: liveness belongs to the batch, not to a row, so the scheduler asks the Workflow runtime whether this instance is still running rather than inferring it from how long ago the row was written."),
|
|
44
|
+
sendAt: SQLiteDate.describe("The absolute time this job should send. Equal to creation time for immediate sends."),
|
|
45
|
+
timezone: z.string().nullish().describe("The recipient's IANA timezone for `timezone` mode; null otherwise."),
|
|
46
|
+
localTime: z.string().nullish().describe("The recipient-local time-of-day (e.g. `10:00`) for `timezone` mode; null otherwise."),
|
|
47
|
+
campaignId: z.string().nullish().describe("The marketing campaign this job belongs to, for click/open attribution; null for transactional."),
|
|
48
|
+
locale: Locale.nullish().describe("The language this message is written in, as a BCP-47 tag; null when the recipient never chose one. **Null is not `en`** — it means nothing was chosen, so the render falls back to the kit's English rather than asserting English was picked, the same distinction `pithy_auth_users.locale` draws. It lives on the row because the two renders happen in different places at different times: the subject at enqueue, inside a request that knows the reader, and the body at send, inside a Workflow with no request on it at all. Without a stored locale those two could agree only by accident, and an operator opening a send log had nothing that explained why a subject read the way it did."),
|
|
49
|
+
correlation: z.string().nullish().describe("What this message was *about*, as the caller names it — the discriminator for a template that carries more than one kind of message. Opaque here: this capability never parses it, never renders it, and never puts it on a header or a link. Set at enqueue, matched by `sentSince`, indexed with `createdAt`. **Not `campaignId`**, which is documented marketing-only and is not merely a naming preference: `campaignId` is copied onto every `pithy_email_events` row, grouped by `campaignStats`, and signed into the click/open tracking token that travels in the URL of a delivered email — so a transactional discriminator put there would land in campaign analytics and in a string the recipient's mail client fetches. This column goes nowhere but this row. Null for a template whose id already says everything about what the message is, which is most of them."),
|
|
50
|
+
openTracking: SQLiteBoolean.describe("Whether an open-tracking pixel was injected into the rendered HTML."),
|
|
51
|
+
clickTracking: SQLiteBoolean.describe("Whether links were rewritten to tracked click-callback URLs."),
|
|
52
|
+
messageId: z.string().nullish().describe("The Email Service message id returned on send — the handle that ties an inbound bounce back to this job."),
|
|
53
|
+
error: z.string().nullish().describe("The last error code/message recorded on a failed or retried send; null when healthy."),
|
|
54
|
+
bounceCode: z.string().nullish().describe("The SMTP or Email Service code from a bounce/complaint; null unless the job bounced."),
|
|
55
|
+
bounceType: z.string().nullish().describe("The classification of a bounce (`hard`/`soft`/`complaint`/`auto_reply`); null unless the job bounced."),
|
|
56
|
+
replyTo: z.string().nullish().describe("The `Reply-To` address, when this job should be answered somewhere other than `fromAddress` — a support inbox replying from a no-reply sender is the case this exists for. Null for an ordinary send."),
|
|
57
|
+
inReplyTo: z.string().nullish().describe("The `In-Reply-To` header value, angle brackets included — the message this one answers. Null unless this job is a reply."),
|
|
58
|
+
references: z.string().nullish().describe("The `References` header value, angle-bracketed and space-separated. Stored as the wire string rather than a JSON array because that is exactly what goes on the header, and re-deriving it at send time is a second chance to get threading wrong. Null unless this job is a reply."),
|
|
59
|
+
createdAt: SQLiteDate.describe("When the job row was created."),
|
|
60
|
+
updatedAt: SQLiteDate.describe("When the job row was last written."),
|
|
61
|
+
sentAt: SQLiteDate.nullish().describe("When the send succeeded; null until then.")
|
|
62
|
+
}).describe("One email job in `pithy_email_jobs` — the auditable, retryable record of a single email.");
|
|
63
|
+
//#endregion
|
|
64
|
+
export { EmailJob, EmailJobPayload, SPENT_PAYLOAD };
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
/**
|
|
5
|
+
* One row in `pithy_email_suppressions` — an address that must not be sent to, fed by hard bounces,
|
|
6
|
+
* complaints, and unsubscribes. The send path checks this list before every send and skips a match,
|
|
7
|
+
* recording why. `z.output` is the app shape; `z.input` is the SQLite row.
|
|
8
|
+
*/
|
|
9
|
+
export declare const EmailSuppression: z.ZodObject<{
|
|
10
|
+
id: z.ZodNumber;
|
|
11
|
+
email: z.ZodString;
|
|
12
|
+
reason: z.ZodEnum<{
|
|
13
|
+
complaint: "complaint";
|
|
14
|
+
hard_bounce: "hard_bounce";
|
|
15
|
+
manual: "manual";
|
|
16
|
+
unsubscribe: "unsubscribe";
|
|
17
|
+
}>;
|
|
18
|
+
jobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
19
|
+
environment: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
20
|
+
detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
21
|
+
createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
|
|
22
|
+
expiresAt: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
|
|
23
|
+
}, z.core.$strip>;
|
|
24
|
+
export type EmailSuppression = z.output<typeof EmailSuppression>;
|
|
25
|
+
//# sourceMappingURL=emailSuppression.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"emailSuppression.d.ts","sourceRoot":"","sources":["../../src/data/emailSuppression.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;iBA0BuC,CAAC;AACrE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { SuppressionReason } from "./enums.js";
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
6
|
+
//#region src/data/emailSuppression.ts
|
|
7
|
+
/**
|
|
8
|
+
* One row in `pithy_email_suppressions` — an address that must not be sent to, fed by hard bounces,
|
|
9
|
+
* complaints, and unsubscribes. The send path checks this list before every send and skips a match,
|
|
10
|
+
* recording why. `z.output` is the app shape; `z.input` is the SQLite row.
|
|
11
|
+
*/
|
|
12
|
+
const EmailSuppression = z.object({
|
|
13
|
+
id: z.number().int().describe("Surrogate primary key, autoincremented by SQLite."),
|
|
14
|
+
email: z.string().describe("The suppressed address, lowercased. Uniquely indexed — one row per address."),
|
|
15
|
+
reason: SuppressionReason.describe("Why the address is suppressed: hard bounce, complaint, unsubscribe, or manual."),
|
|
16
|
+
jobId: z.string().nullish().describe("The job that triggered the suppression (a bounce/complaint/unsubscribe), if any. Job ids are per-environment, so pair it with `environment` for context."),
|
|
17
|
+
environment: z.string().nullish().describe("The environment the triggering job came from (e.g. `prod`, `feature-27`). The suppression itself is global; this records where it originated."),
|
|
18
|
+
detail: z.string().nullish().describe("Free-form context — the bounce code or complaint source; null when not applicable."),
|
|
19
|
+
createdAt: SQLiteDate.describe("When the address was suppressed."),
|
|
20
|
+
expiresAt: SQLiteDate.nullish().describe("When a temporary suppression lifts; null for a permanent suppression.")
|
|
21
|
+
}).describe("One suppressed address in `pithy_email_suppressions`.");
|
|
22
|
+
//#endregion
|
|
23
|
+
export { EmailSuppression };
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
/**
|
|
5
|
+
* The closed enums of the email capability. Each is the documented vocabulary for one column, shared
|
|
6
|
+
* across the row schemas, the send path, and the callback/bounce handlers. Stored as text in SQLite.
|
|
7
|
+
*/
|
|
8
|
+
export declare const TemplateCategory: z.ZodEnum<{
|
|
9
|
+
marketing: "marketing";
|
|
10
|
+
transactional: "transactional";
|
|
11
|
+
}>;
|
|
12
|
+
export type TemplateCategory = z.output<typeof TemplateCategory>;
|
|
13
|
+
export declare const EmailKind: z.ZodEnum<{
|
|
14
|
+
elective: "elective";
|
|
15
|
+
transactional: "transactional";
|
|
16
|
+
}>;
|
|
17
|
+
export type EmailKind = z.output<typeof EmailKind>;
|
|
18
|
+
export declare const SendMode: z.ZodEnum<{
|
|
19
|
+
immediate: "immediate";
|
|
20
|
+
scheduled: "scheduled";
|
|
21
|
+
timezone: "timezone";
|
|
22
|
+
}>;
|
|
23
|
+
export type SendMode = z.output<typeof SendMode>;
|
|
24
|
+
/**
|
|
25
|
+
* **`canceled` has one `l` here, and `@pithy-sh/payments` spells it the same way for a different reason.**
|
|
26
|
+
*
|
|
27
|
+
* The kit writes American English (pithy-sh/pithy#434). This enum is the kit's own vocabulary — nobody
|
|
28
|
+
* else names these states, no wire format outside this package carries them — so the spelling was ours to
|
|
29
|
+
* pick, and we picked the one the rest of the prose uses. `PurchaseStatus` in `payments/src/data/status.ts`
|
|
30
|
+
* arrives at the same string from the other direction: `canceled` is Paddle's wire value, and rewriting a
|
|
31
|
+
* vendor's own string would be inventing a translation layer over somebody else's API.
|
|
32
|
+
*
|
|
33
|
+
* Two capabilities, two arguments, one spelling. That is the point — the kit stopped spelling one concept
|
|
34
|
+
* both ways, and neither side has to be re-derived by the next reader.
|
|
35
|
+
*
|
|
36
|
+
* **This was settled before the first publish, and that window is closed.** Every package was `0.0.0`,
|
|
37
|
+
* nothing was on npm, and `0001_init.ts` declares `status` as bare `text` with no CHECK, so no row and no
|
|
38
|
+
* migration ever held the old value. Changing one now would be a breaking change with a real migration
|
|
39
|
+
* behind it.
|
|
40
|
+
*/
|
|
41
|
+
export declare const EmailJobStatus: z.ZodEnum<{
|
|
42
|
+
bounced: "bounced";
|
|
43
|
+
canceled: "canceled";
|
|
44
|
+
failed: "failed";
|
|
45
|
+
pending: "pending";
|
|
46
|
+
scheduled: "scheduled";
|
|
47
|
+
sending: "sending";
|
|
48
|
+
sent: "sent";
|
|
49
|
+
suppressed: "suppressed";
|
|
50
|
+
undispatched: "undispatched";
|
|
51
|
+
}>;
|
|
52
|
+
export type EmailJobStatus = z.output<typeof EmailJobStatus>;
|
|
53
|
+
export declare const EmailEventType: z.ZodEnum<{
|
|
54
|
+
bounce: "bounce";
|
|
55
|
+
click: "click";
|
|
56
|
+
complaint: "complaint";
|
|
57
|
+
failed: "failed";
|
|
58
|
+
open: "open";
|
|
59
|
+
sent: "sent";
|
|
60
|
+
suppressed: "suppressed";
|
|
61
|
+
unsubscribe: "unsubscribe";
|
|
62
|
+
}>;
|
|
63
|
+
export type EmailEventType = z.output<typeof EmailEventType>;
|
|
64
|
+
export declare const BounceType: z.ZodEnum<{
|
|
65
|
+
auto_reply: "auto_reply";
|
|
66
|
+
complaint: "complaint";
|
|
67
|
+
hard: "hard";
|
|
68
|
+
soft: "soft";
|
|
69
|
+
}>;
|
|
70
|
+
export type BounceType = z.output<typeof BounceType>;
|
|
71
|
+
export declare const SuppressionReason: z.ZodEnum<{
|
|
72
|
+
complaint: "complaint";
|
|
73
|
+
hard_bounce: "hard_bounce";
|
|
74
|
+
manual: "manual";
|
|
75
|
+
unsubscribe: "unsubscribe";
|
|
76
|
+
}>;
|
|
77
|
+
export type SuppressionReason = z.output<typeof SuppressionReason>;
|
|
78
|
+
//# sourceMappingURL=enums.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/data/enums.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AAEH,eAAO,MAAM,gBAAgB;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,eAAO,MAAM,SAAS;;;EAInB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD,eAAO,MAAM,QAAQ;;;;EAIlB,CAAC;AACJ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,eAAO,MAAM,cAAc;;;;;;;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,eAAO,MAAM,UAAU;;;;;EAIpB,CAAC;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAErD,eAAO,MAAM,iBAAiB;;;;;EAI3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
//#region src/data/enums.ts
|
|
5
|
+
/**
|
|
6
|
+
* The closed enums of the email capability. Each is the documented vocabulary for one column, shared
|
|
7
|
+
* across the row schemas, the send path, and the callback/bounce handlers. Stored as text in SQLite.
|
|
8
|
+
*/
|
|
9
|
+
const TemplateCategory = z.enum(["transactional", "marketing"]).describe("What a template's message *is*. `transactional` is triggered by a user action (magic link, receipt); `marketing` is promotional, and cannot render at all without an unsubscribe link. The category drives tracking defaults and that hard requirement. Whether a person may *refuse* the message is a separate question, answered by `EmailKind` — a testing-program nudge is transactional in style and elective in consent.");
|
|
10
|
+
const EmailKind = z.enum(["transactional", "elective"]).describe("Whether a recipient may refuse a message. `transactional` answers something the person just did — a sign-in link, an invitation they are waiting on, a security notice — and carries no unsubscribe affordance and no `List-Unsubscribe` header; `elective` is mail somebody chose to receive and carries both. The kind is declared by the template, never passed by a caller, and it decides how the suppression list is consulted: an unsubscribe blocks elective mail only, while a bounce or a complaint blocks everything.");
|
|
11
|
+
const SendMode = z.enum([
|
|
12
|
+
"immediate",
|
|
13
|
+
"scheduled",
|
|
14
|
+
"timezone"
|
|
15
|
+
]).describe("How a job's send time is determined. `immediate` sends now (a Workflow starts at enqueue); `scheduled` sends at a fixed absolute time; `timezone` resolves a recipient's local time-of-day to an absolute time using their IANA zone.");
|
|
16
|
+
/**
|
|
17
|
+
* **`canceled` has one `l` here, and `@pithy-sh/payments` spells it the same way for a different reason.**
|
|
18
|
+
*
|
|
19
|
+
* The kit writes American English (pithy-sh/pithy#434). This enum is the kit's own vocabulary — nobody
|
|
20
|
+
* else names these states, no wire format outside this package carries them — so the spelling was ours to
|
|
21
|
+
* pick, and we picked the one the rest of the prose uses. `PurchaseStatus` in `payments/src/data/status.ts`
|
|
22
|
+
* arrives at the same string from the other direction: `canceled` is Paddle's wire value, and rewriting a
|
|
23
|
+
* vendor's own string would be inventing a translation layer over somebody else's API.
|
|
24
|
+
*
|
|
25
|
+
* Two capabilities, two arguments, one spelling. That is the point — the kit stopped spelling one concept
|
|
26
|
+
* both ways, and neither side has to be re-derived by the next reader.
|
|
27
|
+
*
|
|
28
|
+
* **This was settled before the first publish, and that window is closed.** Every package was `0.0.0`,
|
|
29
|
+
* nothing was on npm, and `0001_init.ts` declares `status` as bare `text` with no CHECK, so no row and no
|
|
30
|
+
* migration ever held the old value. Changing one now would be a breaking change with a real migration
|
|
31
|
+
* behind it.
|
|
32
|
+
*/
|
|
33
|
+
const EmailJobStatus = z.enum([
|
|
34
|
+
"pending",
|
|
35
|
+
"scheduled",
|
|
36
|
+
"sending",
|
|
37
|
+
"sent",
|
|
38
|
+
"failed",
|
|
39
|
+
"suppressed",
|
|
40
|
+
"bounced",
|
|
41
|
+
"undispatched",
|
|
42
|
+
"canceled"
|
|
43
|
+
]).describe("The lifecycle state of an email job. `pending` (immediate, awaiting dispatch) and `scheduled` (future sendAt) are pre-send; `sending` is in-flight; `sent` succeeded; `failed` exhausted retries; `suppressed` was skipped because the address is on the suppression list; `bounced` was reported undeliverable; `undispatched` means this composition binds no send Workflow, so nothing was started and nothing is coming while that holds — a configuration fact, not a transient one, and the scheduler claims those rows once a host worker exists; `canceled` was withdrawn before sending.");
|
|
44
|
+
const EmailEventType = z.enum([
|
|
45
|
+
"sent",
|
|
46
|
+
"open",
|
|
47
|
+
"click",
|
|
48
|
+
"bounce",
|
|
49
|
+
"complaint",
|
|
50
|
+
"unsubscribe",
|
|
51
|
+
"suppressed",
|
|
52
|
+
"failed"
|
|
53
|
+
]).describe("A per-recipient event recorded for history and campaign attribution: `sent` on a successful send, `open` from the tracking pixel, `click` from a tracked link, `bounce`/`complaint` from inbound mail, `unsubscribe` from the opt-out callback, `suppressed` when a send was skipped, `failed` on a terminal send error.");
|
|
54
|
+
const BounceType = z.enum([
|
|
55
|
+
"hard",
|
|
56
|
+
"soft",
|
|
57
|
+
"complaint",
|
|
58
|
+
"auto_reply"
|
|
59
|
+
]).describe("How an inbound delivery-status or complaint message was classified: `hard` (permanent — suppress), `soft` (transient — Cloudflare auto-retries), `complaint` (recipient reported spam — suppress), `auto_reply` (vacation responder — a no-op, never suppressed).");
|
|
60
|
+
const SuppressionReason = z.enum([
|
|
61
|
+
"hard_bounce",
|
|
62
|
+
"complaint",
|
|
63
|
+
"unsubscribe",
|
|
64
|
+
"manual"
|
|
65
|
+
]).describe("Why an address is on the suppression list and will not be sent to: `hard_bounce` (permanent delivery failure), `complaint` (spam report), `unsubscribe` (recipient opted out), `manual` (added by an operator).");
|
|
66
|
+
//#endregion
|
|
67
|
+
export { BounceType, EmailEventType, EmailJobStatus, EmailKind, SendMode, SuppressionReason, TemplateCategory };
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { D1Database } from "@cloudflare/workers-types";
|
|
4
|
+
import { type DatabaseSchema } from "@pithy-sh/core/src/data/db";
|
|
5
|
+
import type { Kysely } from "kysely";
|
|
6
|
+
/**
|
|
7
|
+
* The email capability spans two databases. Jobs and events are **per-environment** — they live in the
|
|
8
|
+
* app `DB`, alongside the app's own data, scoped to the environment that sent them. Suppression is
|
|
9
|
+
* **global** — an address that hard-bounced, complained, or unsubscribed must never be emailed from any
|
|
10
|
+
* environment — so it lives in a dedicated, durable `EMAIL_SUPPRESSIONS` database (the same shared-DB
|
|
11
|
+
* pattern `@pithy-sh/secrets` uses), written by the single inbound bounce worker and the unsubscribe
|
|
12
|
+
* callbacks and read by every environment's send path.
|
|
13
|
+
*/
|
|
14
|
+
/** The per-environment email tables, on the app `DB`. */
|
|
15
|
+
export declare const emailTables: {
|
|
16
|
+
pithyEmailJobs: import("zod").ZodObject<{
|
|
17
|
+
id: import("zod").ZodString;
|
|
18
|
+
toAddress: import("zod").ZodString;
|
|
19
|
+
recipientKey: import("zod").ZodString;
|
|
20
|
+
fromAddress: import("zod").ZodString;
|
|
21
|
+
fromName: import("zod").ZodString;
|
|
22
|
+
subject: import("zod").ZodString;
|
|
23
|
+
template: import("zod").ZodString;
|
|
24
|
+
category: import("zod").ZodEnum<{
|
|
25
|
+
marketing: "marketing";
|
|
26
|
+
transactional: "transactional";
|
|
27
|
+
}>;
|
|
28
|
+
payload: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>]>, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
|
|
29
|
+
payloadRedactedAt: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>>>;
|
|
30
|
+
status: import("zod").ZodEnum<{
|
|
31
|
+
bounced: "bounced";
|
|
32
|
+
canceled: "canceled";
|
|
33
|
+
failed: "failed";
|
|
34
|
+
pending: "pending";
|
|
35
|
+
scheduled: "scheduled";
|
|
36
|
+
sending: "sending";
|
|
37
|
+
sent: "sent";
|
|
38
|
+
suppressed: "suppressed";
|
|
39
|
+
undispatched: "undispatched";
|
|
40
|
+
}>;
|
|
41
|
+
mode: import("zod").ZodEnum<{
|
|
42
|
+
immediate: "immediate";
|
|
43
|
+
scheduled: "scheduled";
|
|
44
|
+
timezone: "timezone";
|
|
45
|
+
}>;
|
|
46
|
+
attempts: import("zod").ZodNumber;
|
|
47
|
+
batchId: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
48
|
+
sendAt: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>;
|
|
49
|
+
timezone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
50
|
+
localTime: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
51
|
+
campaignId: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
52
|
+
locale: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
53
|
+
correlation: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
54
|
+
openTracking: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodLiteral<0>, import("zod").ZodLiteral<1>, import("zod").ZodBoolean, import("zod").ZodString]>, import("zod").ZodBoolean>;
|
|
55
|
+
clickTracking: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodLiteral<0>, import("zod").ZodLiteral<1>, import("zod").ZodBoolean, import("zod").ZodString]>, import("zod").ZodBoolean>;
|
|
56
|
+
messageId: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
57
|
+
error: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
58
|
+
bounceCode: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
59
|
+
bounceType: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
60
|
+
replyTo: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
61
|
+
inReplyTo: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
62
|
+
references: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
63
|
+
createdAt: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>;
|
|
64
|
+
updatedAt: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>;
|
|
65
|
+
sentAt: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>>>;
|
|
66
|
+
}, import("zod/v4/core").$strip>;
|
|
67
|
+
pithyEmailEvents: import("zod").ZodObject<{
|
|
68
|
+
id: import("zod").ZodNumber;
|
|
69
|
+
jobId: import("zod").ZodString;
|
|
70
|
+
recipient: import("zod").ZodString;
|
|
71
|
+
type: import("zod").ZodEnum<{
|
|
72
|
+
bounce: "bounce";
|
|
73
|
+
click: "click";
|
|
74
|
+
complaint: "complaint";
|
|
75
|
+
failed: "failed";
|
|
76
|
+
open: "open";
|
|
77
|
+
sent: "sent";
|
|
78
|
+
suppressed: "suppressed";
|
|
79
|
+
unsubscribe: "unsubscribe";
|
|
80
|
+
}>;
|
|
81
|
+
linkLabel: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
82
|
+
linkUrl: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
83
|
+
campaignId: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
84
|
+
detail: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
85
|
+
createdAt: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>;
|
|
86
|
+
}, import("zod/v4/core").$strip>;
|
|
87
|
+
};
|
|
88
|
+
export type EmailTables = typeof emailTables;
|
|
89
|
+
/** The global suppression table, on the dedicated durable `EMAIL_SUPPRESSIONS` database. */
|
|
90
|
+
export declare const emailSuppressionTables: {
|
|
91
|
+
pithyEmailSuppressions: import("zod").ZodObject<{
|
|
92
|
+
id: import("zod").ZodNumber;
|
|
93
|
+
email: import("zod").ZodString;
|
|
94
|
+
reason: import("zod").ZodEnum<{
|
|
95
|
+
complaint: "complaint";
|
|
96
|
+
hard_bounce: "hard_bounce";
|
|
97
|
+
manual: "manual";
|
|
98
|
+
unsubscribe: "unsubscribe";
|
|
99
|
+
}>;
|
|
100
|
+
jobId: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
101
|
+
environment: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
102
|
+
detail: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
|
|
103
|
+
createdAt: import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>;
|
|
104
|
+
expiresAt: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>>>;
|
|
105
|
+
}, import("zod/v4/core").$strip>;
|
|
106
|
+
};
|
|
107
|
+
export type EmailSuppressionTables = typeof emailSuppressionTables;
|
|
108
|
+
/** The typed Kysely database over the per-environment email tables (jobs + events). */
|
|
109
|
+
export type EmailDatabase = Kysely<DatabaseSchema<EmailTables>>;
|
|
110
|
+
/** The typed Kysely database over the global suppression table. */
|
|
111
|
+
export type EmailSuppressionDatabase = Kysely<DatabaseSchema<EmailSuppressionTables>>;
|
|
112
|
+
/** Build the per-environment email database from the app `DB` binding (CamelCasePlugin installed). */
|
|
113
|
+
export declare function emailDatabase(d1: D1Database): EmailDatabase;
|
|
114
|
+
/** Build the global suppression database from the `EMAIL_SUPPRESSIONS` binding. */
|
|
115
|
+
export declare function emailSuppressionDatabase(d1: D1Database): EmailSuppressionDatabase;
|
|
116
|
+
//# sourceMappingURL=tables.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKrC;;;;;;;GAOG;AAEH,yDAAyD;AACzD,eAAO,MAAM,WAAW;IACtB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACd,gBAAgB;;;;;;;;;;;;;;;;;;;;CACjB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAE7C,4FAA4F;AAC5F,eAAO,MAAM,sBAAsB;IACjC,sBAAsB;;;;;;;;;;;;;;;CACvB,CAAC;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC;AAEnE,uFAAuF;AACvF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC;AAEhE,mEAAmE;AACnE,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC,CAAC;AAEtF,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,UAAU,GAAG,wBAAwB,CAEjF"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { EmailEvent } from "./emailEvent.js";
|
|
4
|
+
import { EmailJob } from "./emailJob.js";
|
|
5
|
+
import { EmailSuppression } from "./emailSuppression.js";
|
|
6
|
+
import { createDatabase } from "@pithy-sh/core/src/data/db";
|
|
7
|
+
//#region src/data/tables.ts
|
|
8
|
+
/**
|
|
9
|
+
* The email capability spans two databases. Jobs and events are **per-environment** — they live in the
|
|
10
|
+
* app `DB`, alongside the app's own data, scoped to the environment that sent them. Suppression is
|
|
11
|
+
* **global** — an address that hard-bounced, complained, or unsubscribed must never be emailed from any
|
|
12
|
+
* environment — so it lives in a dedicated, durable `EMAIL_SUPPRESSIONS` database (the same shared-DB
|
|
13
|
+
* pattern `@pithy-sh/secrets` uses), written by the single inbound bounce worker and the unsubscribe
|
|
14
|
+
* callbacks and read by every environment's send path.
|
|
15
|
+
*/
|
|
16
|
+
/** The per-environment email tables, on the app `DB`. */
|
|
17
|
+
const emailTables = {
|
|
18
|
+
pithyEmailJobs: EmailJob,
|
|
19
|
+
pithyEmailEvents: EmailEvent
|
|
20
|
+
};
|
|
21
|
+
/** The global suppression table, on the dedicated durable `EMAIL_SUPPRESSIONS` database. */
|
|
22
|
+
const emailSuppressionTables = { pithyEmailSuppressions: EmailSuppression };
|
|
23
|
+
/** Build the per-environment email database from the app `DB` binding (CamelCasePlugin installed). */
|
|
24
|
+
function emailDatabase(d1) {
|
|
25
|
+
return createDatabase(d1, emailTables);
|
|
26
|
+
}
|
|
27
|
+
/** Build the global suppression database from the `EMAIL_SUPPRESSIONS` binding. */
|
|
28
|
+
function emailSuppressionDatabase(d1) {
|
|
29
|
+
return createDatabase(d1, emailSuppressionTables);
|
|
30
|
+
}
|
|
31
|
+
//#endregion
|
|
32
|
+
export { emailDatabase, emailSuppressionDatabase, emailSuppressionTables, emailTables };
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { PithyError } from "@pithy-sh/core/src/error/pithyError";
|
|
4
|
+
import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
|
|
5
|
+
/**
|
|
6
|
+
* `@pithy-sh/email` throw sugar. The `email/*` codes live in core's closed `KitErrorPayload` union
|
|
7
|
+
* (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
|
|
8
|
+
* package-local vehicles that set one of those members — the same pattern as `@pithy-sh/secrets`.
|
|
9
|
+
* Runtime code in this package throws one of these, never a plain `new Error`.
|
|
10
|
+
*/
|
|
11
|
+
/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
|
|
12
|
+
interface EmailErrorArgs {
|
|
13
|
+
/** Override the public, safe-to-expose message. */
|
|
14
|
+
message?: string;
|
|
15
|
+
/** A remediation hint (CLI action line). */
|
|
16
|
+
action?: string;
|
|
17
|
+
/** Internal context for logs + audit. Never serialized to clients. */
|
|
18
|
+
detail?: string;
|
|
19
|
+
/**
|
|
20
|
+
* Values a translating client interpolates into its own wording for this code. Client-facing, so —
|
|
21
|
+
* unlike `action` and `detail` — these cross the boundary with `message`.
|
|
22
|
+
*/
|
|
23
|
+
params?: MessageParams;
|
|
24
|
+
}
|
|
25
|
+
/** The requested template id is not registered. */
|
|
26
|
+
export declare class EmailTemplateNotFoundError extends PithyError {
|
|
27
|
+
constructor(args?: EmailErrorArgs, options?: {
|
|
28
|
+
cause?: unknown;
|
|
29
|
+
});
|
|
30
|
+
}
|
|
31
|
+
/** A template's input variables failed validation against its payload schema. */
|
|
32
|
+
export declare class EmailInvalidPayloadError extends PithyError {
|
|
33
|
+
constructor(args?: EmailErrorArgs, options?: {
|
|
34
|
+
cause?: unknown;
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
/** A callback token (click/open/unsubscribe) is malformed, expired, forged, or signed by an unknown key. */
|
|
38
|
+
export declare class EmailInvalidTokenError extends PithyError {
|
|
39
|
+
constructor(args?: EmailErrorArgs, options?: {
|
|
40
|
+
cause?: unknown;
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
/** The recipient address is on the suppression list and cannot be sent to. */
|
|
44
|
+
export declare class EmailSuppressedError extends PithyError {
|
|
45
|
+
constructor(args?: EmailErrorArgs, options?: {
|
|
46
|
+
cause?: unknown;
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
/** The Email Service rejected the send for a rate or daily-quota limit; the send is retryable. */
|
|
50
|
+
export declare class EmailRateLimitedError extends PithyError {
|
|
51
|
+
constructor(args?: EmailErrorArgs, options?: {
|
|
52
|
+
cause?: unknown;
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
/** A send through the Email Service binding failed for a non-retryable reason. */
|
|
56
|
+
export declare class EmailSendFailedError extends PithyError {
|
|
57
|
+
constructor(args?: EmailErrorArgs, options?: {
|
|
58
|
+
cause?: unknown;
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
export {};
|
|
62
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;;;;GAKG;AAEH,uFAAuF;AACvF,UAAU,cAAc;IACtB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,mDAAmD;AACnD,qBAAa,0BAA2B,SAAQ,UAAU;IACxD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,iFAAiF;AACjF,qBAAa,wBAAyB,SAAQ,UAAU;IACtD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,4GAA4G;AAC5G,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,8EAA8E;AAC9E,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,kGAAkG;AAClG,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,kFAAkF;AAClF,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF"}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { PithyError } from "@pithy-sh/core/src/error/pithyError";
|
|
4
|
+
//#region src/error/errors.ts
|
|
5
|
+
/** The requested template id is not registered. */
|
|
6
|
+
var EmailTemplateNotFoundError = class extends PithyError {
|
|
7
|
+
constructor(args = {}, options) {
|
|
8
|
+
super({
|
|
9
|
+
code: "email/template_not_found",
|
|
10
|
+
status: 404,
|
|
11
|
+
message: args.message ?? "Email template not found.",
|
|
12
|
+
action: args.action,
|
|
13
|
+
detail: args.detail,
|
|
14
|
+
params: args.params
|
|
15
|
+
}, options);
|
|
16
|
+
}
|
|
17
|
+
};
|
|
18
|
+
/** A template's input variables failed validation against its payload schema. */
|
|
19
|
+
var EmailInvalidPayloadError = class extends PithyError {
|
|
20
|
+
constructor(args = {}, options) {
|
|
21
|
+
super({
|
|
22
|
+
code: "email/invalid_payload",
|
|
23
|
+
status: 400,
|
|
24
|
+
message: args.message ?? "Email template payload failed validation.",
|
|
25
|
+
action: args.action,
|
|
26
|
+
detail: args.detail,
|
|
27
|
+
params: args.params
|
|
28
|
+
}, options);
|
|
29
|
+
}
|
|
30
|
+
};
|
|
31
|
+
/** A callback token (click/open/unsubscribe) is malformed, expired, forged, or signed by an unknown key. */
|
|
32
|
+
var EmailInvalidTokenError = class extends PithyError {
|
|
33
|
+
constructor(args = {}, options) {
|
|
34
|
+
super({
|
|
35
|
+
code: "email/invalid_token",
|
|
36
|
+
status: 400,
|
|
37
|
+
message: args.message ?? "This link is invalid or has expired.",
|
|
38
|
+
action: args.action,
|
|
39
|
+
detail: args.detail,
|
|
40
|
+
params: args.params
|
|
41
|
+
}, options);
|
|
42
|
+
}
|
|
43
|
+
};
|
|
44
|
+
/** The recipient address is on the suppression list and cannot be sent to. */
|
|
45
|
+
var EmailSuppressedError = class extends PithyError {
|
|
46
|
+
constructor(args = {}, options) {
|
|
47
|
+
super({
|
|
48
|
+
code: "email/suppressed",
|
|
49
|
+
status: 409,
|
|
50
|
+
message: args.message ?? "This address is suppressed and cannot be emailed.",
|
|
51
|
+
action: args.action,
|
|
52
|
+
detail: args.detail,
|
|
53
|
+
params: args.params
|
|
54
|
+
}, options);
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
/** The Email Service rejected the send for a rate or daily-quota limit; the send is retryable. */
|
|
58
|
+
var EmailRateLimitedError = class extends PithyError {
|
|
59
|
+
constructor(args = {}, options) {
|
|
60
|
+
super({
|
|
61
|
+
code: "email/rate_limited",
|
|
62
|
+
status: 429,
|
|
63
|
+
message: args.message ?? "The email rate limit was exceeded.",
|
|
64
|
+
action: args.action ?? "Retry with backoff.",
|
|
65
|
+
detail: args.detail,
|
|
66
|
+
params: args.params
|
|
67
|
+
}, options);
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
/** A send through the Email Service binding failed for a non-retryable reason. */
|
|
71
|
+
var EmailSendFailedError = class extends PithyError {
|
|
72
|
+
constructor(args = {}, options) {
|
|
73
|
+
super({
|
|
74
|
+
code: "email/send_failed",
|
|
75
|
+
status: 502,
|
|
76
|
+
message: args.message ?? "The email could not be sent.",
|
|
77
|
+
action: args.action,
|
|
78
|
+
detail: args.detail,
|
|
79
|
+
params: args.params
|
|
80
|
+
}, options);
|
|
81
|
+
}
|
|
82
|
+
};
|
|
83
|
+
//#endregion
|
|
84
|
+
export { EmailInvalidPayloadError, EmailInvalidTokenError, EmailRateLimitedError, EmailSendFailedError, EmailSuppressedError, EmailTemplateNotFoundError };
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
4
|
+
import type { Hono } from "hono";
|
|
5
|
+
import { type EmailDatabase, type EmailSuppressionDatabase } from "../data/tables";
|
|
6
|
+
/** The signing-key version set a handler verifies against. */
|
|
7
|
+
export interface SigningKeys {
|
|
8
|
+
versions: Record<string, string>;
|
|
9
|
+
}
|
|
10
|
+
/** Handle a click: record it, then 302-redirect to the signed http(s) destination. */
|
|
11
|
+
export declare function handleClick(db: EmailDatabase, keys: SigningKeys, token: string, now: Date): Promise<Response>;
|
|
12
|
+
/** Handle an open: record it, return the 1×1 pixel. */
|
|
13
|
+
export declare function handleOpen(db: EmailDatabase, keys: SigningKeys, token: string, now: Date): Promise<Response>;
|
|
14
|
+
/**
|
|
15
|
+
* Handle an unsubscribe: suppress the address (shared DB), record the opt-out event (app DB), confirm.
|
|
16
|
+
* An optional `reason` — supplied by the app's own unsubscribe/preferences flow via the `?reason=` query
|
|
17
|
+
* param — is stored on the suppression `detail` and the event, so a project can capture *why* someone
|
|
18
|
+
* opted out using its own logic. It is length-bounded so the link can't be used to stuff the column.
|
|
19
|
+
*/
|
|
20
|
+
export declare function handleUnsubscribe(db: EmailDatabase, suppressionDb: EmailSuppressionDatabase, keys: SigningKeys, token: string, now: Date, reason?: string, environment?: string): Promise<Response>;
|
|
21
|
+
/** Mount the click/open/unsubscribe callback routes under `${CALLBACK_BASE}` on the app's Hono router. */
|
|
22
|
+
export declare function registerCallbacks(app: Hono<PithyHonoEnv>): void;
|
|
23
|
+
//# sourceMappingURL=callbacks.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/http/callbacks.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAGjC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAG9B,MAAM,gBAAgB,CAAC;AAwCxB,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAiBD,sFAAsF;AACtF,wBAAsB,WAAW,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmBnH;AAED,uDAAuD;AACvD,wBAAsB,UAAU,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgBlH;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,aAAa,EAAE,wBAAwB,EACvC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,QAAQ,CAAC,CAuBnB;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAyC/D"}
|