@pithy-sh/email 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/analytics.d.ts +19 -0
- package/dist/analytics.d.ts.map +1 -0
- package/dist/analytics.js +13 -0
- package/dist/audit/actions.d.ts +45 -0
- package/dist/audit/actions.d.ts.map +1 -0
- package/dist/audit/actions.js +45 -0
- package/dist/bounce/classify.d.ts +38 -0
- package/dist/bounce/classify.d.ts.map +1 -0
- package/dist/bounce/classify.js +46 -0
- package/dist/bounce/handler.d.ts +32 -0
- package/dist/bounce/handler.d.ts.map +1 -0
- package/dist/bounce/handler.js +81 -0
- package/dist/capability.d.ts +158 -0
- package/dist/capability.d.ts.map +1 -0
- package/dist/capability.js +255 -0
- package/dist/crypto/signingKey.d.ts +36 -0
- package/dist/crypto/signingKey.d.ts.map +1 -0
- package/dist/crypto/signingKey.js +36 -0
- package/dist/crypto/token.d.ts +47 -0
- package/dist/crypto/token.d.ts.map +1 -0
- package/dist/crypto/token.js +99 -0
- package/dist/data/emailEvent.d.ts +28 -0
- package/dist/data/emailEvent.d.ts.map +1 -0
- package/dist/data/emailEvent.js +22 -0
- package/dist/data/emailJob.d.ts +76 -0
- package/dist/data/emailJob.d.ts.map +1 -0
- package/dist/data/emailJob.js +62 -0
- package/dist/data/emailSuppression.d.ts +23 -0
- package/dist/data/emailSuppression.d.ts.map +1 -0
- package/dist/data/emailSuppression.js +21 -0
- package/dist/data/enums.d.ts +76 -0
- package/dist/data/enums.d.ts.map +1 -0
- package/dist/data/enums.js +65 -0
- package/dist/data/tables.d.ts +114 -0
- package/dist/data/tables.d.ts.map +1 -0
- package/dist/data/tables.js +30 -0
- package/dist/error/errors.d.ts +60 -0
- package/dist/error/errors.d.ts.map +1 -0
- package/dist/error/errors.js +82 -0
- package/dist/http/callbacks.d.ts +21 -0
- package/dist/http/callbacks.d.ts.map +1 -0
- package/dist/http/callbacks.js +110 -0
- package/dist/http/guards.d.ts +99 -0
- package/dist/http/guards.d.ts.map +1 -0
- package/dist/http/guards.js +144 -0
- package/dist/http/responses.d.ts +295 -0
- package/dist/http/responses.d.ts.map +1 -0
- package/dist/http/responses.js +115 -0
- package/dist/http/routes.d.ts +71 -0
- package/dist/http/routes.d.ts.map +1 -0
- package/dist/http/routes.js +292 -0
- package/dist/http/schemas.d.ts +90 -0
- package/dist/http/schemas.d.ts.map +1 -0
- package/dist/http/schemas.js +91 -0
- package/dist/http/view.d.ts +78 -0
- package/dist/http/view.d.ts.map +1 -0
- package/dist/http/view.js +130 -0
- package/dist/index.d.ts +46 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/jobs/read.d.ts +191 -0
- package/dist/jobs/read.d.ts.map +1 -0
- package/dist/jobs/read.js +143 -0
- package/dist/jobs/retry.d.ts +99 -0
- package/dist/jobs/retry.d.ts.map +1 -0
- package/dist/jobs/retry.js +67 -0
- package/dist/migrations/0001_init.d.ts +32 -0
- package/dist/migrations/0001_init.d.ts.map +1 -0
- package/dist/migrations/0001_init.js +60 -0
- package/dist/migrations/0001_suppressions.d.ts +10 -0
- package/dist/migrations/0001_suppressions.d.ts.map +1 -0
- package/dist/migrations/0001_suppressions.js +20 -0
- package/dist/provision/devDelivery.d.ts +32 -0
- package/dist/provision/devDelivery.d.ts.map +1 -0
- package/dist/provision/devDelivery.js +37 -0
- package/dist/provision/hostCatalogs.d.ts +10 -0
- package/dist/provision/hostCatalogs.d.ts.map +1 -0
- package/dist/provision/hostCatalogs.js +78 -0
- package/dist/provision/provisionEmail.d.ts +143 -0
- package/dist/provision/provisionEmail.d.ts.map +1 -0
- package/dist/provision/provisionEmail.js +118 -0
- package/dist/provision/resolveEmailConfig.d.ts +122 -0
- package/dist/provision/resolveEmailConfig.d.ts.map +1 -0
- package/dist/provision/resolveEmailConfig.js +124 -0
- package/dist/provision/settingsCheck.d.ts +40 -0
- package/dist/provision/settingsCheck.d.ts.map +1 -0
- package/dist/provision/settingsCheck.js +138 -0
- package/dist/send/batchIdentity.d.ts +42 -0
- package/dist/send/batchIdentity.d.ts.map +1 -0
- package/dist/send/batchIdentity.js +46 -0
- package/dist/send/enqueue.d.ts +216 -0
- package/dist/send/enqueue.d.ts.map +1 -0
- package/dist/send/enqueue.js +153 -0
- package/dist/send/errorMapping.d.ts +27 -0
- package/dist/send/errorMapping.d.ts.map +1 -0
- package/dist/send/errorMapping.js +52 -0
- package/dist/send/events.d.ts +15 -0
- package/dist/send/events.d.ts.map +1 -0
- package/dist/send/events.js +17 -0
- package/dist/send/fromComposition.d.ts +47 -0
- package/dist/send/fromComposition.d.ts.map +1 -0
- package/dist/send/fromComposition.js +53 -0
- package/dist/send/retryPolicy.d.ts +32 -0
- package/dist/send/retryPolicy.d.ts.map +1 -0
- package/dist/send/retryPolicy.js +39 -0
- package/dist/send/runSend.d.ts +106 -0
- package/dist/send/runSend.d.ts.map +1 -0
- package/dist/send/runSend.js +218 -0
- package/dist/send/sendAt.d.ts +6 -0
- package/dist/send/sendAt.d.ts.map +1 -0
- package/dist/send/sendAt.js +62 -0
- package/dist/send/sender.d.ts +42 -0
- package/dist/send/sender.d.ts.map +1 -0
- package/dist/send/sender.js +0 -0
- package/dist/send/senderBinding.d.ts +44 -0
- package/dist/send/senderBinding.d.ts.map +1 -0
- package/dist/send/senderBinding.js +21 -0
- package/dist/send/suppression.d.ts +93 -0
- package/dist/send/suppression.d.ts.map +1 -0
- package/dist/send/suppression.js +132 -0
- package/dist/templates/engine.d.ts +109 -0
- package/dist/templates/engine.d.ts.map +1 -0
- package/dist/templates/engine.js +258 -0
- package/dist/templates/messages.d.ts +94 -0
- package/dist/templates/messages.d.ts.map +1 -0
- package/dist/templates/messages.es.d.ts +29 -0
- package/dist/templates/messages.es.d.ts.map +1 -0
- package/dist/templates/messages.es.js +82 -0
- package/dist/templates/messages.js +266 -0
- package/dist/templates/partials.d.ts +5 -0
- package/dist/templates/partials.d.ts.map +1 -0
- package/dist/templates/partials.js +59 -0
- package/dist/templates/precompiled.generated.d.ts +266 -0
- package/dist/templates/precompiled.generated.d.ts.map +1 -0
- package/dist/templates/precompiled.generated.js +4039 -0
- package/dist/templates/registry.d.ts +118 -0
- package/dist/templates/registry.d.ts.map +1 -0
- package/dist/templates/registry.js +323 -0
- package/dist/templates/samples.d.ts +7 -0
- package/dist/templates/samples.d.ts.map +1 -0
- package/dist/templates/samples.js +98 -0
- package/dist/templates/severity.d.ts +40 -0
- package/dist/templates/severity.d.ts.map +1 -0
- package/dist/templates/severity.js +81 -0
- package/dist/templates/theme.d.ts +193 -0
- package/dist/templates/theme.d.ts.map +1 -0
- package/dist/templates/theme.js +168 -0
- package/dist/version.generated.d.ts +5 -0
- package/dist/version.generated.d.ts.map +1 -0
- package/dist/version.generated.js +7 -0
- package/dist/workflows/hostApp.d.ts +33 -0
- package/dist/workflows/hostApp.d.ts.map +1 -0
- package/dist/workflows/hostApp.js +19 -0
- package/dist/workflows/hostEnv.d.ts +129 -0
- package/dist/workflows/hostEnv.d.ts.map +1 -0
- package/dist/workflows/hostEnv.js +147 -0
- package/dist/workflows/instanceLiveness.d.ts +3 -0
- package/dist/workflows/instanceLiveness.d.ts.map +1 -0
- package/dist/workflows/instanceLiveness.js +37 -0
- package/dist/workflows/instances.d.ts +18 -0
- package/dist/workflows/instances.d.ts.map +1 -0
- package/dist/workflows/instances.js +0 -0
- package/dist/workflows/params.d.ts +23 -0
- package/dist/workflows/params.d.ts.map +1 -0
- package/dist/workflows/params.js +21 -0
- package/dist/workflows/scheduler.d.ts +82 -0
- package/dist/workflows/scheduler.d.ts.map +1 -0
- package/dist/workflows/scheduler.js +111 -0
- package/dist/workflows/sendBatch.d.ts +85 -0
- package/dist/workflows/sendBatch.d.ts.map +1 -0
- package/dist/workflows/sendBatch.js +50 -0
- package/dist/workflows/worker.d.ts +100 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +117 -0
- package/package.json +22 -11
- package/src/version.generated.ts +1 -1
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { EmailInvalidPayloadError } from "../error/errors.js";
|
|
2
|
+
import { normalizeIanaTimezone } from "@pithy-sh/core/src/data/codecs";
|
|
3
|
+
//#region src/send/sendAt.ts
|
|
4
|
+
/**
|
|
5
|
+
* Resolve a job's absolute send time from its mode. `immediate` is now; `scheduled` is the given
|
|
6
|
+
* absolute instant; `timezone` resolves a recipient-local time-of-day (e.g. `10:00`) in their IANA
|
|
7
|
+
* zone to the next absolute instant at or after now. The timezone math uses `Intl` only — no library —
|
|
8
|
+
* by measuring the zone's offset at a candidate instant and correcting for it.
|
|
9
|
+
*/
|
|
10
|
+
/** The offset (ms) of a timezone at a given UTC instant: zone wall-clock minus UTC. */
|
|
11
|
+
function zoneOffsetMs(timezone, utcMs) {
|
|
12
|
+
const parts = new Intl.DateTimeFormat("en-US", {
|
|
13
|
+
timeZone: timezone,
|
|
14
|
+
hour12: false,
|
|
15
|
+
year: "numeric",
|
|
16
|
+
month: "2-digit",
|
|
17
|
+
day: "2-digit",
|
|
18
|
+
hour: "2-digit",
|
|
19
|
+
minute: "2-digit",
|
|
20
|
+
second: "2-digit"
|
|
21
|
+
}).formatToParts(new Date(utcMs));
|
|
22
|
+
const get = (type) => Number(parts.find((p) => p.type === type)?.value ?? "0");
|
|
23
|
+
const hour = get("hour") % 24;
|
|
24
|
+
return Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second")) - utcMs;
|
|
25
|
+
}
|
|
26
|
+
/** Parse `HH:MM` to `{ hour, minute }`, or throw `email/invalid_payload`. */
|
|
27
|
+
function parseLocalTime(localTime) {
|
|
28
|
+
const match = /^(\d{1,2}):(\d{2})$/.exec(localTime.trim());
|
|
29
|
+
const hour = match ? Number(match[1]) : NaN;
|
|
30
|
+
const minute = match ? Number(match[2]) : NaN;
|
|
31
|
+
if (!match || hour < 0 || hour > 23 || minute < 0 || minute > 59) throw new EmailInvalidPayloadError({ detail: `invalid localTime '${localTime}' — expected HH:MM` });
|
|
32
|
+
return {
|
|
33
|
+
hour,
|
|
34
|
+
minute
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* The next absolute instant when the wall clock reads `hour:minute` in `timezone`, at or after `now`.
|
|
39
|
+
* Computes the candidate for the zone-local date of `now`, advancing a day if it has already passed.
|
|
40
|
+
*/
|
|
41
|
+
function resolveTimezoneSendAt(localTime, timezone, now) {
|
|
42
|
+
const zone = normalizeIanaTimezone(timezone);
|
|
43
|
+
if (!zone) throw new EmailInvalidPayloadError({ detail: `invalid IANA timezone '${timezone}'` });
|
|
44
|
+
const { hour, minute } = parseLocalTime(localTime);
|
|
45
|
+
const dateParts = new Intl.DateTimeFormat("en-CA", {
|
|
46
|
+
timeZone: zone,
|
|
47
|
+
year: "numeric",
|
|
48
|
+
month: "2-digit",
|
|
49
|
+
day: "2-digit"
|
|
50
|
+
}).formatToParts(now);
|
|
51
|
+
const part = (type) => Number(dateParts.find((p) => p.type === type)?.value ?? "0");
|
|
52
|
+
const candidateFor = (dayOffset) => {
|
|
53
|
+
const guessUtc = Date.UTC(part("year"), part("month") - 1, part("day") + dayOffset, hour, minute);
|
|
54
|
+
const first = guessUtc - zoneOffsetMs(zone, guessUtc);
|
|
55
|
+
const secondOffset = zoneOffsetMs(zone, first);
|
|
56
|
+
return new Date(guessUtc - secondOffset);
|
|
57
|
+
};
|
|
58
|
+
const today = candidateFor(0);
|
|
59
|
+
return today.getTime() >= now.getTime() ? today : candidateFor(1);
|
|
60
|
+
}
|
|
61
|
+
//#endregion
|
|
62
|
+
export { resolveTimezoneSendAt };
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The minimal shape of the Cloudflare Email Service `send_email` binding this capability depends on.
|
|
3
|
+
* We type only what we use, structurally — the real binding (`env.EMAIL`) satisfies it, and tests
|
|
4
|
+
* inject a fake so send outcomes are deterministic. The binding sends both `html` and `text` and
|
|
5
|
+
* returns a `messageId`; it throws on failure with an `E_*` `.code` (mapped by `errorMapping`).
|
|
6
|
+
*/
|
|
7
|
+
/** An outbound message handed to the binding — html + text both, per deliverability best practice. */
|
|
8
|
+
export interface EmailMessage {
|
|
9
|
+
/** The recipient address. */
|
|
10
|
+
to: string;
|
|
11
|
+
/** The sender — address plus display name. */
|
|
12
|
+
from: {
|
|
13
|
+
email: string;
|
|
14
|
+
name?: string;
|
|
15
|
+
};
|
|
16
|
+
/** Optional reply-to address. */
|
|
17
|
+
replyTo?: string;
|
|
18
|
+
/** The rendered subject line. */
|
|
19
|
+
subject: string;
|
|
20
|
+
/** The rendered HTML body. */
|
|
21
|
+
html: string;
|
|
22
|
+
/** The rendered plain-text body. */
|
|
23
|
+
text: string;
|
|
24
|
+
/** Optional whitelisted headers (e.g. `List-Unsubscribe`). */
|
|
25
|
+
headers?: Record<string, string>;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* The send response. The Workers binding returns a `messageId`; the batch/REST shape additionally
|
|
29
|
+
* reports `delivered`/`permanentBounces`/`queued`. We capture all of it so synchronous permanent
|
|
30
|
+
* bounces can feed suppression immediately, and the `messageId` ties an asynchronous bounce back.
|
|
31
|
+
*/
|
|
32
|
+
export interface EmailSendResult {
|
|
33
|
+
messageId?: string;
|
|
34
|
+
delivered?: string[];
|
|
35
|
+
permanentBounces?: string[];
|
|
36
|
+
queued?: string[];
|
|
37
|
+
}
|
|
38
|
+
/** The send seam. `env.EMAIL` satisfies it; tests pass a fake. */
|
|
39
|
+
export interface EmailSender {
|
|
40
|
+
send(message: EmailMessage): Promise<EmailSendResult>;
|
|
41
|
+
}
|
|
42
|
+
//# sourceMappingURL=sender.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../src/send/sender.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,sGAAsG;AACtG,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACvD"}
|
|
File without changes
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { SendWorkflowBinding } from "./enqueue";
|
|
2
|
+
/**
|
|
3
|
+
* Where the send Workflow comes from — one answer, for the two call sites that need it.
|
|
4
|
+
*
|
|
5
|
+
* `email().enqueue` and the admin retry route both start a send, and both used to read
|
|
6
|
+
* `env.EMAIL_SENDER` straight off the request env. Under `pithy dev` that binding does not exist:
|
|
7
|
+
* it is a **cross-script** binding at `<project>-dev-email`, and no local script runs under that
|
|
8
|
+
* name, so every immediate send was born `undispatched` and the local loop was silent
|
|
9
|
+
* (pithy-sh/pithy#410). A module rather than a line in each place, because the day the two answers
|
|
10
|
+
* differ is the day one of them stops sending mail and nothing says so.
|
|
11
|
+
*/
|
|
12
|
+
/**
|
|
13
|
+
* What deciding the sender reads off the env, and nothing else.
|
|
14
|
+
*
|
|
15
|
+
* Three keys, not the whole enqueue env: `DB` and the suppression list are somebody else's question,
|
|
16
|
+
* and a narrower parameter is what lets the admin routes' own env shape pass without a cast.
|
|
17
|
+
*/
|
|
18
|
+
export interface EmailSenderEnv {
|
|
19
|
+
/** The bound send Workflow. Present in every deployed environment; absent under `pithy dev`. */
|
|
20
|
+
EMAIL_SENDER?: SendWorkflowBinding;
|
|
21
|
+
/**
|
|
22
|
+
* The environment this composition was stamped for — `pithy init` writes it into every Worker's
|
|
23
|
+
* `wrangler.jsonc`. Read only to refuse: a substitution happens in `dev` and nowhere else.
|
|
24
|
+
*/
|
|
25
|
+
ENVIRONMENT?: string;
|
|
26
|
+
/**
|
|
27
|
+
* The local email host's address, written by `pithy dev` as a `--var`. Present only in `dev`, where
|
|
28
|
+
* it is what stands in for the cross-script binding no local script can provide.
|
|
29
|
+
*/
|
|
30
|
+
EMAIL_ORIGIN?: string;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* The Workflow that starts a send: the bound one, or — under `pithy dev` — a loopback dispatcher
|
|
34
|
+
* addressed at the local email host.
|
|
35
|
+
*
|
|
36
|
+
* The rules are core's ({@link resolveWorkflowBinding}) and are stated there. The one thing decided
|
|
37
|
+
* here is that email's host is the capability named `email`, which is what makes the var
|
|
38
|
+
* `EMAIL_ORIGIN`.
|
|
39
|
+
*
|
|
40
|
+
* **Absent still means absent.** A composition with no binding and no local host enqueues the row
|
|
41
|
+
* `undispatched` exactly as it did — this fills the seam, it never invents one.
|
|
42
|
+
*/
|
|
43
|
+
export declare function emailSenderBinding(env: EmailSenderEnv): SendWorkflowBinding | undefined;
|
|
44
|
+
//# sourceMappingURL=senderBinding.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"senderBinding.d.ts","sourceRoot":"","sources":["../../src/send/senderBinding.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gGAAgG;IAChG,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,mBAAmB,GAAG,SAAS,CAMvF"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { resolveWorkflowBinding } from "@pithy-sh/core/src/workflow/dispatch";
|
|
2
|
+
//#region src/send/senderBinding.ts
|
|
3
|
+
/**
|
|
4
|
+
* The Workflow that starts a send: the bound one, or — under `pithy dev` — a loopback dispatcher
|
|
5
|
+
* addressed at the local email host.
|
|
6
|
+
*
|
|
7
|
+
* The rules are core's ({@link resolveWorkflowBinding}) and are stated there. The one thing decided
|
|
8
|
+
* here is that email's host is the capability named `email`, which is what makes the var
|
|
9
|
+
* `EMAIL_ORIGIN`.
|
|
10
|
+
*
|
|
11
|
+
* **Absent still means absent.** A composition with no binding and no local host enqueues the row
|
|
12
|
+
* `undispatched` exactly as it did — this fills the seam, it never invents one.
|
|
13
|
+
*/
|
|
14
|
+
function emailSenderBinding(env) {
|
|
15
|
+
return resolveWorkflowBinding(env, {
|
|
16
|
+
binding: "EMAIL_SENDER",
|
|
17
|
+
capability: "email"
|
|
18
|
+
});
|
|
19
|
+
}
|
|
20
|
+
//#endregion
|
|
21
|
+
export { emailSenderBinding };
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { EmailSuppression } from "../data/emailSuppression";
|
|
2
|
+
import { type EmailKind, SuppressionReason } from "../data/enums";
|
|
3
|
+
import type { EmailSuppressionDatabase } from "../data/tables";
|
|
4
|
+
/**
|
|
5
|
+
* The suppression list: addresses that must not be emailed, fed by hard bounces, complaints, and
|
|
6
|
+
* unsubscribes. The send path checks it before every send and skips a match, naming the reason it
|
|
7
|
+
* skipped for.
|
|
8
|
+
*
|
|
9
|
+
* Every address here goes through `normalizeAddress` from core, so a check and a write agree on the
|
|
10
|
+
* key — and so does `auth` matching a sign-in, `support` linking a sender, and `testers` reading this
|
|
11
|
+
* very table. A suppression written under one rule and read under another is a suppression that does
|
|
12
|
+
* not suppress, and it reports itself as "the list did not work" rather than as anything about case.
|
|
13
|
+
*
|
|
14
|
+
* The list is also the one thing in this capability a management client both reads and writes, and it
|
|
15
|
+
* is **global** — one database shared by every environment, so a row here stops mail from staging and
|
|
16
|
+
* production alike. That is why reading it, adding to it, and removing from it are three separate
|
|
17
|
+
* control-plane scopes rather than one.
|
|
18
|
+
*
|
|
19
|
+
* **The reason is part of the answer, not just a label on the row.** The list is keyed by address and
|
|
20
|
+
* holds no memory of which message a person was refusing, so treating every reason alike meant one
|
|
21
|
+
* unsubscribe from a weekly digest also withheld that person's sign-in link — and passwordless has no
|
|
22
|
+
* password to fall back on. `suppressionBlocks` is where the four reasons stop being interchangeable.
|
|
23
|
+
*/
|
|
24
|
+
/**
|
|
25
|
+
* Whether a live suppression for this reason blocks a message of this kind.
|
|
26
|
+
*
|
|
27
|
+
* | reason | elective | transactional |
|
|
28
|
+
* |---|---|---|
|
|
29
|
+
* | `hard_bounce` | block | **block** — the mailbox does not exist. Sending is futile, and hammering dead addresses damages the sending domain for every other adopter on it. |
|
|
30
|
+
* | `complaint` | block | **block** — they reported us as spam. Continuing after a complaint is how a domain gets blocked outright. |
|
|
31
|
+
* | `unsubscribe` | block | **send** — an opt-out is a statement about mail somebody chose to receive. A sign-in link is not that; withholding it respects no preference, it locks the account. |
|
|
32
|
+
* | `manual` | block | block — an operator's deliberate act, and the one reason a human can point at. Narrowing it would silently overrule the person who set it. |
|
|
33
|
+
*
|
|
34
|
+
* Bounce and complaint are facts about the mailbox; unsubscribe and manual are decisions about mail.
|
|
35
|
+
* Only the unsubscribe decision is about a *category* of mail, which is why it is the only one the kind
|
|
36
|
+
* can narrow.
|
|
37
|
+
*/
|
|
38
|
+
export declare function suppressionBlocks(reason: SuppressionReason, kind: EmailKind): boolean;
|
|
39
|
+
/**
|
|
40
|
+
* The live suppression reason blocking a message of this kind, or `null` if nothing does.
|
|
41
|
+
*
|
|
42
|
+
* The kind is required rather than defaulted. A default would have to be one of the two, and the one
|
|
43
|
+
* that reads as safe — block everything — is the one that locks people out of their own accounts.
|
|
44
|
+
*/
|
|
45
|
+
export declare function blockingSuppression(db: EmailSuppressionDatabase, email: string, now: Date, kind: EmailKind): Promise<SuppressionReason | null>;
|
|
46
|
+
/** Add (or refresh) a suppression for an address. Idempotent on the unique `email` column. */
|
|
47
|
+
export declare function suppress(db: EmailSuppressionDatabase, input: {
|
|
48
|
+
email: string;
|
|
49
|
+
reason: SuppressionReason;
|
|
50
|
+
jobId?: string | null;
|
|
51
|
+
environment?: string | null;
|
|
52
|
+
detail?: string | null;
|
|
53
|
+
expiresAt?: Date | null;
|
|
54
|
+
}, now: Date): Promise<void>;
|
|
55
|
+
/**
|
|
56
|
+
* Remove a suppression. Returns whether a row was actually removed.
|
|
57
|
+
*
|
|
58
|
+
* The boolean matters: an operator unblocking an address that was never blocked, and one unblocking an
|
|
59
|
+
* address that was, are two different events and the audit trail should not record them as the same
|
|
60
|
+
* one. It also keeps the route idempotent — asking twice is not an error, it is simply the second one
|
|
61
|
+
* finding nothing to do.
|
|
62
|
+
*
|
|
63
|
+
* There is no soft delete. A suppression is a "do not send" flag, and a lifted flag that stays in the
|
|
64
|
+
* table is one bad query away from still being enforced.
|
|
65
|
+
*/
|
|
66
|
+
export declare function unsuppress(db: EmailSuppressionDatabase, email: string): Promise<boolean>;
|
|
67
|
+
/** What the suppression list filters and pages by. */
|
|
68
|
+
export interface SuppressionListFilter {
|
|
69
|
+
/** One reason, or every reason when absent. */
|
|
70
|
+
reason?: SuppressionReason;
|
|
71
|
+
/** Look one address up exactly, rather than paging the list. */
|
|
72
|
+
email?: string;
|
|
73
|
+
/** The previous page's `nextCursor`. A malformed one is a first page. */
|
|
74
|
+
cursor?: string;
|
|
75
|
+
/** How many rows to return, clamped into range. */
|
|
76
|
+
limit?: number;
|
|
77
|
+
}
|
|
78
|
+
/** One page of the suppression list. */
|
|
79
|
+
export interface SuppressionPage {
|
|
80
|
+
/** The suppressed addresses, most recently blocked first. */
|
|
81
|
+
items: EmailSuppression[];
|
|
82
|
+
/** Where the next page starts, or null at the end of the list. */
|
|
83
|
+
nextCursor: string | null;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* One page of the suppression list, most recently blocked first.
|
|
87
|
+
*
|
|
88
|
+
* Keyset, never offset — the same rule every list in this repo follows, and it applies here even though
|
|
89
|
+
* the table is quieter than the job log: a hard bounce arriving mid-scroll would otherwise skip a row
|
|
90
|
+
* for the person reading it.
|
|
91
|
+
*/
|
|
92
|
+
export declare function listSuppressions(db: EmailSuppressionDatabase, filter: SuppressionListFilter): Promise<SuppressionPage>;
|
|
93
|
+
//# sourceMappingURL=suppression.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"suppression.d.ts","sourceRoot":"","sources":["../../src/send/suppression.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,KAAK,SAAS,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAGrF;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,wBAAwB,EAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAkBnC;AAED,8FAA8F;AAC9F,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,wBAAwB,EAC5B,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB,EACD,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,wBAAwB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM9F;AAED,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAeD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,wBAAwB,EAC5B,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAyB1B"}
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import { SuppressionReason } from "../data/enums.js";
|
|
2
|
+
import { EmailSuppression } from "../data/emailSuppression.js";
|
|
3
|
+
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
4
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
5
|
+
import { decodeCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
|
|
6
|
+
//#region src/send/suppression.ts
|
|
7
|
+
/**
|
|
8
|
+
* The suppression list: addresses that must not be emailed, fed by hard bounces, complaints, and
|
|
9
|
+
* unsubscribes. The send path checks it before every send and skips a match, naming the reason it
|
|
10
|
+
* skipped for.
|
|
11
|
+
*
|
|
12
|
+
* Every address here goes through `normalizeAddress` from core, so a check and a write agree on the
|
|
13
|
+
* key — and so does `auth` matching a sign-in, `support` linking a sender, and `testers` reading this
|
|
14
|
+
* very table. A suppression written under one rule and read under another is a suppression that does
|
|
15
|
+
* not suppress, and it reports itself as "the list did not work" rather than as anything about case.
|
|
16
|
+
*
|
|
17
|
+
* The list is also the one thing in this capability a management client both reads and writes, and it
|
|
18
|
+
* is **global** — one database shared by every environment, so a row here stops mail from staging and
|
|
19
|
+
* production alike. That is why reading it, adding to it, and removing from it are three separate
|
|
20
|
+
* control-plane scopes rather than one.
|
|
21
|
+
*
|
|
22
|
+
* **The reason is part of the answer, not just a label on the row.** The list is keyed by address and
|
|
23
|
+
* holds no memory of which message a person was refusing, so treating every reason alike meant one
|
|
24
|
+
* unsubscribe from a weekly digest also withheld that person's sign-in link — and passwordless has no
|
|
25
|
+
* password to fall back on. `suppressionBlocks` is where the four reasons stop being interchangeable.
|
|
26
|
+
*/
|
|
27
|
+
/**
|
|
28
|
+
* Whether a live suppression for this reason blocks a message of this kind.
|
|
29
|
+
*
|
|
30
|
+
* | reason | elective | transactional |
|
|
31
|
+
* |---|---|---|
|
|
32
|
+
* | `hard_bounce` | block | **block** — the mailbox does not exist. Sending is futile, and hammering dead addresses damages the sending domain for every other adopter on it. |
|
|
33
|
+
* | `complaint` | block | **block** — they reported us as spam. Continuing after a complaint is how a domain gets blocked outright. |
|
|
34
|
+
* | `unsubscribe` | block | **send** — an opt-out is a statement about mail somebody chose to receive. A sign-in link is not that; withholding it respects no preference, it locks the account. |
|
|
35
|
+
* | `manual` | block | block — an operator's deliberate act, and the one reason a human can point at. Narrowing it would silently overrule the person who set it. |
|
|
36
|
+
*
|
|
37
|
+
* Bounce and complaint are facts about the mailbox; unsubscribe and manual are decisions about mail.
|
|
38
|
+
* Only the unsubscribe decision is about a *category* of mail, which is why it is the only one the kind
|
|
39
|
+
* can narrow.
|
|
40
|
+
*/
|
|
41
|
+
function suppressionBlocks(reason, kind) {
|
|
42
|
+
if (reason === "unsubscribe") return kind === "elective";
|
|
43
|
+
return true;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* The live suppression reason blocking a message of this kind, or `null` if nothing does.
|
|
47
|
+
*
|
|
48
|
+
* The kind is required rather than defaulted. A default would have to be one of the two, and the one
|
|
49
|
+
* that reads as safe — block everything — is the one that locks people out of their own accounts.
|
|
50
|
+
*/
|
|
51
|
+
async function blockingSuppression(db, email, now, kind) {
|
|
52
|
+
const row = await db.selectFrom("pithyEmailSuppressions").select(["reason", "expiresAt"]).where("email", "=", normalizeAddress(email)).executeTakeFirst();
|
|
53
|
+
if (!row) return null;
|
|
54
|
+
if (!(row.expiresAt === null || row.expiresAt === void 0 || SQLiteDate.parse(row.expiresAt).getTime() > now.getTime())) return null;
|
|
55
|
+
const parsed = SuppressionReason.safeParse(row.reason);
|
|
56
|
+
if (!parsed.success) return "manual";
|
|
57
|
+
return suppressionBlocks(parsed.data, kind) ? parsed.data : null;
|
|
58
|
+
}
|
|
59
|
+
/** Add (or refresh) a suppression for an address. Idempotent on the unique `email` column. */
|
|
60
|
+
async function suppress(db, input, now) {
|
|
61
|
+
const email = normalizeAddress(input.email);
|
|
62
|
+
const jobId = input.jobId ?? null;
|
|
63
|
+
const environment = input.environment ?? null;
|
|
64
|
+
const detail = input.detail ?? null;
|
|
65
|
+
const expiresAt = input.expiresAt ? SQLiteDate.encode(input.expiresAt) : null;
|
|
66
|
+
await db.insertInto("pithyEmailSuppressions").values({
|
|
67
|
+
email,
|
|
68
|
+
reason: input.reason,
|
|
69
|
+
jobId,
|
|
70
|
+
environment,
|
|
71
|
+
detail,
|
|
72
|
+
expiresAt,
|
|
73
|
+
createdAt: SQLiteDate.encode(now)
|
|
74
|
+
}).onConflict((oc) => oc.column("email").doUpdateSet({
|
|
75
|
+
reason: input.reason,
|
|
76
|
+
jobId,
|
|
77
|
+
environment,
|
|
78
|
+
detail,
|
|
79
|
+
expiresAt
|
|
80
|
+
})).execute();
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Remove a suppression. Returns whether a row was actually removed.
|
|
84
|
+
*
|
|
85
|
+
* The boolean matters: an operator unblocking an address that was never blocked, and one unblocking an
|
|
86
|
+
* address that was, are two different events and the audit trail should not record them as the same
|
|
87
|
+
* one. It also keeps the route idempotent — asking twice is not an error, it is simply the second one
|
|
88
|
+
* finding nothing to do.
|
|
89
|
+
*
|
|
90
|
+
* There is no soft delete. A suppression is a "do not send" flag, and a lifted flag that stays in the
|
|
91
|
+
* table is one bad query away from still being enforced.
|
|
92
|
+
*/
|
|
93
|
+
async function unsuppress(db, email) {
|
|
94
|
+
return ((await db.deleteFrom("pithyEmailSuppressions").where("email", "=", normalizeAddress(email)).executeTakeFirst()).numDeletedRows ?? 0n) > 0n;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* A cursor this table can resume from.
|
|
98
|
+
*
|
|
99
|
+
* Both halves must be numbers here — `createdAt` is a ms-epoch and `id` is an autoincrement integer —
|
|
100
|
+
* and anything else is treated exactly as a malformed cursor is. A string compared against an integer
|
|
101
|
+
* column in SQLite does not fail; it orders by something nobody meant, which is worse.
|
|
102
|
+
*/
|
|
103
|
+
function suppressionCursor(raw) {
|
|
104
|
+
const cursor = decodeCursor(raw);
|
|
105
|
+
if (!cursor || typeof cursor.sort !== "number" || typeof cursor.id !== "number") return void 0;
|
|
106
|
+
return {
|
|
107
|
+
sort: cursor.sort,
|
|
108
|
+
id: cursor.id
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* One page of the suppression list, most recently blocked first.
|
|
113
|
+
*
|
|
114
|
+
* Keyset, never offset — the same rule every list in this repo follows, and it applies here even though
|
|
115
|
+
* the table is quieter than the job log: a hard bounce arriving mid-scroll would otherwise skip a row
|
|
116
|
+
* for the person reading it.
|
|
117
|
+
*/
|
|
118
|
+
async function listSuppressions(db, filter) {
|
|
119
|
+
const limit = pageLimit(filter.limit);
|
|
120
|
+
const after = suppressionCursor(filter.cursor);
|
|
121
|
+
let query = db.selectFrom("pithyEmailSuppressions").selectAll().orderBy("createdAt", "desc").orderBy("id", "desc").limit(limit + 1);
|
|
122
|
+
if (filter.reason) query = query.where("reason", "=", filter.reason);
|
|
123
|
+
if (filter.email) query = query.where("email", "=", normalizeAddress(filter.email));
|
|
124
|
+
if (after) query = query.where((eb) => eb.or([eb("createdAt", "<", after.sort), eb.and([eb("createdAt", "=", after.sort), eb("id", "<", after.id)])]));
|
|
125
|
+
const items = (await query.execute()).map((row) => EmailSuppression.parse(row));
|
|
126
|
+
return toPage(items, limit, (row) => ({
|
|
127
|
+
sort: row.createdAt.getTime(),
|
|
128
|
+
id: row.id
|
|
129
|
+
}));
|
|
130
|
+
}
|
|
131
|
+
//#endregion
|
|
132
|
+
export { blockingSuppression, listSuppressions, suppress, suppressionBlocks, unsuppress };
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import type { Translator } from "@pithy-sh/core/src/i18n/translator";
|
|
2
|
+
import type { EmailKind } from "../data/enums";
|
|
3
|
+
import { type EmailTemplate } from "./registry";
|
|
4
|
+
import { type EmailTheme } from "./theme";
|
|
5
|
+
/**
|
|
6
|
+
* The render engine. Templates are compiled **once at module load** — which in a Worker happens during
|
|
7
|
+
* isolate startup, where dynamic compilation is permitted — and cached, so a send never compiles or
|
|
8
|
+
* evals at request time (CLAUDE.md §Email: "precompiled, no runtime compile/eval"). Rendering is then
|
|
9
|
+
* pure string substitution.
|
|
10
|
+
*
|
|
11
|
+
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (signing
|
|
12
|
+
* is async; Handlebars helpers are not) and the resulting URLs are placed into the render context.
|
|
13
|
+
* Click tracking rewrites the declared link locations; open tracking injects a pixel; and an **elective**
|
|
14
|
+
* template gets an unsubscribe link, which a marketing template additionally cannot render without.
|
|
15
|
+
*
|
|
16
|
+
* **A transactional template can never be given one.** The affordance is gated on the kind the template
|
|
17
|
+
* itself declares, so there is no argument a call site could pass to put an opt-out on a sign-in link —
|
|
18
|
+
* and `renderEmail` reports the URL it minted, so the send path sets `List-Unsubscribe` from what was
|
|
19
|
+
* actually rendered rather than from a second, drift-prone judgment of its own.
|
|
20
|
+
*/
|
|
21
|
+
/** The mount prefix of the callback routes. Tracking URLs are built against `${baseUrl}${CALLBACK_BASE}`. */
|
|
22
|
+
export declare const CALLBACK_BASE = "/_pithy/email";
|
|
23
|
+
/** The signing + addressing context a tracked render needs. Shaped to plug straight into the send path. */
|
|
24
|
+
export interface RenderTracking {
|
|
25
|
+
/** The public base URL of the app worker; callback links are built against it. */
|
|
26
|
+
baseUrl: string;
|
|
27
|
+
/** The job this render belongs to — embedded in every token. */
|
|
28
|
+
jobId: string;
|
|
29
|
+
/** The recipient address — embedded in every token. */
|
|
30
|
+
recipient: string;
|
|
31
|
+
/** The marketing campaign id, for click/open attribution. */
|
|
32
|
+
campaignId?: string;
|
|
33
|
+
/** The current signing key value (from `@pithy-sh/secrets`). */
|
|
34
|
+
key: string;
|
|
35
|
+
/** The current signing key version, recorded as the token `kid`. */
|
|
36
|
+
kid: string;
|
|
37
|
+
/** When the tokens (and so the links) expire. */
|
|
38
|
+
expiresAt: Date;
|
|
39
|
+
/** Whether to inject the open-tracking pixel. */
|
|
40
|
+
openTracking: boolean;
|
|
41
|
+
/** Whether to rewrite links to tracked click callbacks. */
|
|
42
|
+
clickTracking: boolean;
|
|
43
|
+
}
|
|
44
|
+
/** A rendered email: the three parts a send needs, plus the opt-out URL it actually carries. */
|
|
45
|
+
export interface RenderResult {
|
|
46
|
+
subject: string;
|
|
47
|
+
html: string;
|
|
48
|
+
text: string;
|
|
49
|
+
/**
|
|
50
|
+
* The unsubscribe URL rendered into the body, when one was. Present only for an elective template with
|
|
51
|
+
* a signing context; the send path turns it into the `List-Unsubscribe` header, so the header and the
|
|
52
|
+
* link in the body can never disagree about whether this message can be opted out of.
|
|
53
|
+
*/
|
|
54
|
+
unsubscribeUrl?: string;
|
|
55
|
+
}
|
|
56
|
+
/** Look up a template by id, or throw `email/template_not_found`. */
|
|
57
|
+
export declare function getTemplate(id: string): EmailTemplate;
|
|
58
|
+
/**
|
|
59
|
+
* The kind a template declares — the one answer to "may this message be refused".
|
|
60
|
+
*
|
|
61
|
+
* An id nobody registered is reported as `elective`, deliberately. It cannot be *proved* transactional,
|
|
62
|
+
* and the alternative reading would let a template deleted in a later release quietly reopen sending to
|
|
63
|
+
* addresses that opted out. Nothing is locked out by the choice: a job naming an unknown template fails
|
|
64
|
+
* at render moments later either way, so this only decides which of two failures gets reported.
|
|
65
|
+
*/
|
|
66
|
+
export declare function templateKind(templateId: string): EmailKind;
|
|
67
|
+
/**
|
|
68
|
+
* Whether this template's payload is dropped once the message is delivered.
|
|
69
|
+
*
|
|
70
|
+
* **Keyed on the category, not the kind.** The kind answers "may this be refused"; this question is
|
|
71
|
+
* "are these inputs a one-time credential". `testerNudge` is the template that proves they are
|
|
72
|
+
* different axes — it is *elective*, because somebody may say stop chasing me, and its payload carries
|
|
73
|
+
* an opt-in URL that authenticates a tester. Keying on the kind would have left exactly that one live.
|
|
74
|
+
*
|
|
75
|
+
* A transactional message is a reply to something one person just did, and its payload is that
|
|
76
|
+
* person's one-time input: a sign-in URL, a code, an invitation token. A marketing message's payload is
|
|
77
|
+
* copy authored for a batch, carrying no per-recipient credential and answering the real question
|
|
78
|
+
* "what did the forty thousand of them actually receive". So the category is the line, and it falls in
|
|
79
|
+
* the right place on every template in the registry.
|
|
80
|
+
*
|
|
81
|
+
* There is no per-template override, because no template needs one today and an escape hatch nobody
|
|
82
|
+
* uses is where the bug comes back. The day a marketing template carries a per-recipient credential,
|
|
83
|
+
* the override is the change to make — with a reason written beside it.
|
|
84
|
+
*
|
|
85
|
+
* An id nobody registered redacts, which is the safe direction and, like `templateKind`, decides
|
|
86
|
+
* nothing real: a job naming an unknown template fails at render and never reaches a delivery.
|
|
87
|
+
*/
|
|
88
|
+
export declare function redactsPayloadOnDelivery(templateId: string): boolean;
|
|
89
|
+
/** The registered template ids, for introspection and the CLI. */
|
|
90
|
+
export declare function listTemplates(): EmailTemplate[];
|
|
91
|
+
/**
|
|
92
|
+
* Validate a payload against its template and render just the subject line. Used at enqueue to fail
|
|
93
|
+
* fast on a bad payload and to store the job's subject without rendering the whole body. Throws
|
|
94
|
+
* `email/template_not_found` or `email/invalid_payload`.
|
|
95
|
+
*/
|
|
96
|
+
export declare function renderSubject(templateId: string, payload: unknown, theme: EmailTheme, translator?: Translator): string;
|
|
97
|
+
/**
|
|
98
|
+
* Render a template to `{ subject, html, text }`. Validates the payload against the template's schema
|
|
99
|
+
* (throws `email/invalid_payload`), applies click/open tracking and — for an elective template — the
|
|
100
|
+
* unsubscribe link, then substitutes. A marketing template with no tracking context throws: it cannot
|
|
101
|
+
* render without an unsubscribe link.
|
|
102
|
+
*
|
|
103
|
+
* The opt-out rule is two-tier on purpose. Every elective template carries the link *when the engine can
|
|
104
|
+
* mint one*; a marketing template additionally *refuses to render* without it. Tying the hard refusal to
|
|
105
|
+
* the kind instead would mean a project that has not configured a link-signing key suddenly cannot send
|
|
106
|
+
* its testing-cohort nudges — a new outage, in a change whose whole subject is mail that fails silently.
|
|
107
|
+
*/
|
|
108
|
+
export declare function renderEmail(templateId: string, payload: unknown, theme: EmailTheme, tracking?: RenderTracking, translator?: Translator): Promise<RenderResult>;
|
|
109
|
+
//# sourceMappingURL=engine.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/templates/engine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAGrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,YAAY,CAAC;AAE3D,OAAO,EAAE,KAAK,UAAU,EAAW,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAuH7C,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,SAAS,EAAE,IAAI,CAAC;IAChB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,CAIrD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,aAAa,EAAE,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,UAAU,GAAE,UAAoB,GAC/B,MAAM,CASR;AAyDD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,cAAc,EACzB,UAAU,GAAE,UAAoB,GAC/B,OAAO,CAAC,YAAY,CAAC,CA8DvB"}
|