@pithy-sh/email 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/analytics.d.ts +19 -0
- package/dist/analytics.d.ts.map +1 -0
- package/dist/analytics.js +13 -0
- package/dist/audit/actions.d.ts +45 -0
- package/dist/audit/actions.d.ts.map +1 -0
- package/dist/audit/actions.js +45 -0
- package/dist/bounce/classify.d.ts +38 -0
- package/dist/bounce/classify.d.ts.map +1 -0
- package/dist/bounce/classify.js +46 -0
- package/dist/bounce/handler.d.ts +32 -0
- package/dist/bounce/handler.d.ts.map +1 -0
- package/dist/bounce/handler.js +81 -0
- package/dist/capability.d.ts +158 -0
- package/dist/capability.d.ts.map +1 -0
- package/dist/capability.js +255 -0
- package/dist/crypto/signingKey.d.ts +36 -0
- package/dist/crypto/signingKey.d.ts.map +1 -0
- package/dist/crypto/signingKey.js +36 -0
- package/dist/crypto/token.d.ts +47 -0
- package/dist/crypto/token.d.ts.map +1 -0
- package/dist/crypto/token.js +99 -0
- package/dist/data/emailEvent.d.ts +28 -0
- package/dist/data/emailEvent.d.ts.map +1 -0
- package/dist/data/emailEvent.js +22 -0
- package/dist/data/emailJob.d.ts +76 -0
- package/dist/data/emailJob.d.ts.map +1 -0
- package/dist/data/emailJob.js +62 -0
- package/dist/data/emailSuppression.d.ts +23 -0
- package/dist/data/emailSuppression.d.ts.map +1 -0
- package/dist/data/emailSuppression.js +21 -0
- package/dist/data/enums.d.ts +76 -0
- package/dist/data/enums.d.ts.map +1 -0
- package/dist/data/enums.js +65 -0
- package/dist/data/tables.d.ts +114 -0
- package/dist/data/tables.d.ts.map +1 -0
- package/dist/data/tables.js +30 -0
- package/dist/error/errors.d.ts +60 -0
- package/dist/error/errors.d.ts.map +1 -0
- package/dist/error/errors.js +82 -0
- package/dist/http/callbacks.d.ts +21 -0
- package/dist/http/callbacks.d.ts.map +1 -0
- package/dist/http/callbacks.js +110 -0
- package/dist/http/guards.d.ts +99 -0
- package/dist/http/guards.d.ts.map +1 -0
- package/dist/http/guards.js +144 -0
- package/dist/http/responses.d.ts +295 -0
- package/dist/http/responses.d.ts.map +1 -0
- package/dist/http/responses.js +115 -0
- package/dist/http/routes.d.ts +71 -0
- package/dist/http/routes.d.ts.map +1 -0
- package/dist/http/routes.js +292 -0
- package/dist/http/schemas.d.ts +90 -0
- package/dist/http/schemas.d.ts.map +1 -0
- package/dist/http/schemas.js +91 -0
- package/dist/http/view.d.ts +78 -0
- package/dist/http/view.d.ts.map +1 -0
- package/dist/http/view.js +130 -0
- package/dist/index.d.ts +46 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/jobs/read.d.ts +191 -0
- package/dist/jobs/read.d.ts.map +1 -0
- package/dist/jobs/read.js +143 -0
- package/dist/jobs/retry.d.ts +99 -0
- package/dist/jobs/retry.d.ts.map +1 -0
- package/dist/jobs/retry.js +67 -0
- package/dist/migrations/0001_init.d.ts +32 -0
- package/dist/migrations/0001_init.d.ts.map +1 -0
- package/dist/migrations/0001_init.js +60 -0
- package/dist/migrations/0001_suppressions.d.ts +10 -0
- package/dist/migrations/0001_suppressions.d.ts.map +1 -0
- package/dist/migrations/0001_suppressions.js +20 -0
- package/dist/provision/devDelivery.d.ts +32 -0
- package/dist/provision/devDelivery.d.ts.map +1 -0
- package/dist/provision/devDelivery.js +37 -0
- package/dist/provision/hostCatalogs.d.ts +10 -0
- package/dist/provision/hostCatalogs.d.ts.map +1 -0
- package/dist/provision/hostCatalogs.js +78 -0
- package/dist/provision/provisionEmail.d.ts +143 -0
- package/dist/provision/provisionEmail.d.ts.map +1 -0
- package/dist/provision/provisionEmail.js +118 -0
- package/dist/provision/resolveEmailConfig.d.ts +122 -0
- package/dist/provision/resolveEmailConfig.d.ts.map +1 -0
- package/dist/provision/resolveEmailConfig.js +124 -0
- package/dist/provision/settingsCheck.d.ts +40 -0
- package/dist/provision/settingsCheck.d.ts.map +1 -0
- package/dist/provision/settingsCheck.js +138 -0
- package/dist/send/batchIdentity.d.ts +42 -0
- package/dist/send/batchIdentity.d.ts.map +1 -0
- package/dist/send/batchIdentity.js +46 -0
- package/dist/send/enqueue.d.ts +216 -0
- package/dist/send/enqueue.d.ts.map +1 -0
- package/dist/send/enqueue.js +153 -0
- package/dist/send/errorMapping.d.ts +27 -0
- package/dist/send/errorMapping.d.ts.map +1 -0
- package/dist/send/errorMapping.js +52 -0
- package/dist/send/events.d.ts +15 -0
- package/dist/send/events.d.ts.map +1 -0
- package/dist/send/events.js +17 -0
- package/dist/send/fromComposition.d.ts +47 -0
- package/dist/send/fromComposition.d.ts.map +1 -0
- package/dist/send/fromComposition.js +53 -0
- package/dist/send/retryPolicy.d.ts +32 -0
- package/dist/send/retryPolicy.d.ts.map +1 -0
- package/dist/send/retryPolicy.js +39 -0
- package/dist/send/runSend.d.ts +106 -0
- package/dist/send/runSend.d.ts.map +1 -0
- package/dist/send/runSend.js +218 -0
- package/dist/send/sendAt.d.ts +6 -0
- package/dist/send/sendAt.d.ts.map +1 -0
- package/dist/send/sendAt.js +62 -0
- package/dist/send/sender.d.ts +42 -0
- package/dist/send/sender.d.ts.map +1 -0
- package/dist/send/sender.js +0 -0
- package/dist/send/senderBinding.d.ts +44 -0
- package/dist/send/senderBinding.d.ts.map +1 -0
- package/dist/send/senderBinding.js +21 -0
- package/dist/send/suppression.d.ts +93 -0
- package/dist/send/suppression.d.ts.map +1 -0
- package/dist/send/suppression.js +132 -0
- package/dist/templates/engine.d.ts +109 -0
- package/dist/templates/engine.d.ts.map +1 -0
- package/dist/templates/engine.js +258 -0
- package/dist/templates/messages.d.ts +94 -0
- package/dist/templates/messages.d.ts.map +1 -0
- package/dist/templates/messages.es.d.ts +29 -0
- package/dist/templates/messages.es.d.ts.map +1 -0
- package/dist/templates/messages.es.js +82 -0
- package/dist/templates/messages.js +266 -0
- package/dist/templates/partials.d.ts +5 -0
- package/dist/templates/partials.d.ts.map +1 -0
- package/dist/templates/partials.js +59 -0
- package/dist/templates/precompiled.generated.d.ts +266 -0
- package/dist/templates/precompiled.generated.d.ts.map +1 -0
- package/dist/templates/precompiled.generated.js +4039 -0
- package/dist/templates/registry.d.ts +118 -0
- package/dist/templates/registry.d.ts.map +1 -0
- package/dist/templates/registry.js +323 -0
- package/dist/templates/samples.d.ts +7 -0
- package/dist/templates/samples.d.ts.map +1 -0
- package/dist/templates/samples.js +98 -0
- package/dist/templates/severity.d.ts +40 -0
- package/dist/templates/severity.d.ts.map +1 -0
- package/dist/templates/severity.js +81 -0
- package/dist/templates/theme.d.ts +193 -0
- package/dist/templates/theme.d.ts.map +1 -0
- package/dist/templates/theme.js +168 -0
- package/dist/version.generated.d.ts +5 -0
- package/dist/version.generated.d.ts.map +1 -0
- package/dist/version.generated.js +7 -0
- package/dist/workflows/hostApp.d.ts +33 -0
- package/dist/workflows/hostApp.d.ts.map +1 -0
- package/dist/workflows/hostApp.js +19 -0
- package/dist/workflows/hostEnv.d.ts +129 -0
- package/dist/workflows/hostEnv.d.ts.map +1 -0
- package/dist/workflows/hostEnv.js +147 -0
- package/dist/workflows/instanceLiveness.d.ts +3 -0
- package/dist/workflows/instanceLiveness.d.ts.map +1 -0
- package/dist/workflows/instanceLiveness.js +37 -0
- package/dist/workflows/instances.d.ts +18 -0
- package/dist/workflows/instances.d.ts.map +1 -0
- package/dist/workflows/instances.js +0 -0
- package/dist/workflows/params.d.ts +23 -0
- package/dist/workflows/params.d.ts.map +1 -0
- package/dist/workflows/params.js +21 -0
- package/dist/workflows/scheduler.d.ts +82 -0
- package/dist/workflows/scheduler.d.ts.map +1 -0
- package/dist/workflows/scheduler.js +111 -0
- package/dist/workflows/sendBatch.d.ts +85 -0
- package/dist/workflows/sendBatch.d.ts.map +1 -0
- package/dist/workflows/sendBatch.js +50 -0
- package/dist/workflows/worker.d.ts +100 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +117 -0
- package/package.json +22 -11
- package/src/version.generated.ts +1 -1
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { EmailJobStatus, SuppressionReason } from "../data/enums.js";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
|
|
4
|
+
/**
|
|
5
|
+
* The `:token` path parameter every callback route carries. A shape and size bound only — the ceiling
|
|
6
|
+
* is generous enough for a click token whose signed claims embed a long destination URL, so no link we
|
|
7
|
+
* mint can exceed it, while an unbounded segment can no longer reach the verifier.
|
|
8
|
+
*/
|
|
9
|
+
const CallbackTokenParam = z.object({ token: z.string().min(1).max(4096).regex(/^[A-Za-z0-9._-]+$/).describe("The signed callback token from the path, optionally with the open-pixel `.png` suffix.") }).describe("The path parameter carrying a click/open/unsubscribe callback token.");
|
|
10
|
+
/**
|
|
11
|
+
* The optional `?reason=` on the unsubscribe callback — supplied by the app's own preferences flow.
|
|
12
|
+
* The bound is a ceiling, not the storage limit: the handler still truncates to 200 characters before
|
|
13
|
+
* writing, so every real value keeps behaving exactly as it did and only an absurd one is refused.
|
|
14
|
+
*/
|
|
15
|
+
const UnsubscribeQuery = z.object({ reason: z.string().max(2e3).optional().describe("Why the recipient opted out; truncated to 200 characters before it is stored.") }).describe("The optional query parameters accepted by the unsubscribe callback.");
|
|
16
|
+
/**
|
|
17
|
+
* Where the next page starts. Opaque, and a malformed one is a first page rather than a 400 — the
|
|
18
|
+
* decode lives in `@pithy-sh/core/src/data/cursor` and collapses every failure mode to the same
|
|
19
|
+
* undefined, so this bounds the size and nothing else.
|
|
20
|
+
*/
|
|
21
|
+
const Cursor = z.string().max(512).optional().describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page.");
|
|
22
|
+
/** How many rows one page may carry. Bounded, because a verified client can still have a bug. */
|
|
23
|
+
const Limit = z.coerce.number().int().min(1).max(MAX_PAGE_SIZE).optional().describe("How many rows to return. Clamped into range — an unbounded page is a table scan.");
|
|
24
|
+
/**
|
|
25
|
+
* An address as an admin route accepts it for a **write**.
|
|
26
|
+
*
|
|
27
|
+
* Validated as a real address, because blocking a typo blocks nothing and the caller never finds out:
|
|
28
|
+
* a suppression is silent to everyone, so a malformed one is a mistake that only surfaces as mail
|
|
29
|
+
* still arriving. Lowercasing and trimming happen in the handler, through core's `normalizeAddress`,
|
|
30
|
+
* so the stored key always matches what the send path checks — and what every other capability that
|
|
31
|
+
* compares an address arrives at.
|
|
32
|
+
*/
|
|
33
|
+
const WritableAddress = z.email().max(254).describe("The address to block. Normalized (trimmed, lowercased) before it is stored or compared.");
|
|
34
|
+
/**
|
|
35
|
+
* An address as an admin route accepts it for a **read or an undo**, deliberately looser than
|
|
36
|
+
* {@link WritableAddress}.
|
|
37
|
+
*
|
|
38
|
+
* Bounces and inbound complaints write whatever address the remote server reported, and some of those
|
|
39
|
+
* are not addresses a validator would accept. A rule strict enough to keep bad data out of a manual
|
|
40
|
+
* block would also make the row it wrote unreachable — an operator could see a malformed suppression
|
|
41
|
+
* in the list and have no way to lift it. An undo has to be able to reach anything already written.
|
|
42
|
+
*/
|
|
43
|
+
const AddressFilter = z.string().min(3).max(254).includes("@").describe("An address to match exactly, normalized the same way the stored key is.");
|
|
44
|
+
/**
|
|
45
|
+
* The `:id` of one job.
|
|
46
|
+
*
|
|
47
|
+
* Shape and size, not `.uuid()`. Production ids are `crypto.randomUUID()`, but `newId` is an injected
|
|
48
|
+
* dependency of `enqueueEmail`, so a consumer supplying its own generator would find every one of its
|
|
49
|
+
* jobs answering 400 at a route that never reached the lookup. A param schema constrains the string;
|
|
50
|
+
* the handler still does the lookup and still raises its own 404.
|
|
51
|
+
*/
|
|
52
|
+
const JobIdParam = z.object({ id: z.string().min(1).max(128).regex(/^[A-Za-z0-9._:-]+$/).describe("The job's id, as `pithy_email_jobs.id` stores it.") }).describe("The path parameter of every single-job admin route.");
|
|
53
|
+
/** The job log query. */
|
|
54
|
+
const JobsQuery = z.object({
|
|
55
|
+
status: EmailJobStatus.optional().describe("Filter to one lifecycle state — `failed` is the pane this capability exists for. Absent lists every state."),
|
|
56
|
+
cursor: Cursor,
|
|
57
|
+
limit: Limit
|
|
58
|
+
}).describe("The send-log query: which state to filter by, and where to resume.");
|
|
59
|
+
/**
|
|
60
|
+
* The suppression list query.
|
|
61
|
+
*
|
|
62
|
+
* `email` is an exact-match lookup rather than a search, and that is the point: answering "is this one
|
|
63
|
+
* address blocked" should not require paging a list of every other person who ever unsubscribed. A
|
|
64
|
+
* prefix or substring search would turn the endpoint into a way to enumerate the list a page at a time
|
|
65
|
+
* while looking like a lookup.
|
|
66
|
+
*/
|
|
67
|
+
const SuppressionsQuery = z.object({
|
|
68
|
+
reason: SuppressionReason.optional().describe("Filter to one reason — hard bounce, complaint, unsubscribe, manual."),
|
|
69
|
+
email: AddressFilter.optional().describe("Look one address up, exactly. Answers `is this person blocked` without disclosing anybody else."),
|
|
70
|
+
cursor: Cursor,
|
|
71
|
+
limit: Limit
|
|
72
|
+
}).describe("The suppression-list query: what to filter by, which address to look up, and where to resume.");
|
|
73
|
+
/**
|
|
74
|
+
* Block an address by hand.
|
|
75
|
+
*
|
|
76
|
+
* **There is no `reason` field, on purpose.** The column records *why an address is blocked*, and three
|
|
77
|
+
* of its four values (`hard_bounce`, `complaint`, `unsubscribe`) are facts the system observed: a
|
|
78
|
+
* bounce arrived, a complaint arrived, a recipient followed their own opt-out link. A management client
|
|
79
|
+
* observed none of them, so letting it name one would let an operator's assertion enter the record as
|
|
80
|
+
* an observation, and the deliverability decisions read off that column would be made on fiction. Every
|
|
81
|
+
* address blocked through this route is `manual`, and what the operator knows goes in `detail`.
|
|
82
|
+
*/
|
|
83
|
+
const SuppressRequest = z.object({
|
|
84
|
+
email: WritableAddress,
|
|
85
|
+
detail: z.string().min(1).max(200).optional().describe("Why you are blocking it, in your own words. Stored verbatim on the row and in the audit trail."),
|
|
86
|
+
expiresAt: z.iso.datetime().optional().describe("When the block lifts, as an ISO-8601 instant. **Must be in the future** — checked in the handler against its injected clock rather than here, because a schema reading the wall clock would ignore the clock the route was given. Absent blocks permanently; a time-boxed block expires on its own rather than waiting for somebody to remember it. A past instant is refused because the send path decides purely on `expiresAt <= now`, so backdating one is exactly equivalent to lifting the block — an act this route's scope deliberately does not confer.")
|
|
87
|
+
}).describe("Add one address to the global suppression list, as a manual block.");
|
|
88
|
+
/** Unblock an address — the undo of {@link SuppressRequest}, and of a bounce, complaint, or opt-out. */
|
|
89
|
+
const UnsuppressRequest = z.object({ email: AddressFilter.describe("The address to unblock, matched exactly against the stored key.") }).describe("Remove one address from the global suppression list, re-opening sending to it.");
|
|
90
|
+
//#endregion
|
|
91
|
+
export { CallbackTokenParam, JobIdParam, JobsQuery, SuppressRequest, SuppressionsQuery, UnsubscribeQuery, UnsuppressRequest };
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { EmailJob } from "../data/emailJob";
|
|
2
|
+
import type { EmailSuppression } from "../data/emailSuppression";
|
|
3
|
+
import type { EmailJobDetail, EmailJobListItem, EmailSuppressionView } from "./responses";
|
|
4
|
+
/**
|
|
5
|
+
* What a management client is allowed to see. Nothing in this package ever returns a raw row.
|
|
6
|
+
*
|
|
7
|
+
* ## `payload` is never projected. Anywhere.
|
|
8
|
+
*
|
|
9
|
+
* `EmailJob.payload` holds the template's input variables, and that is not merely "often PII" — it is
|
|
10
|
+
* the most sensitive column this capability owns. A `magicLink` job's payload contains the sign-in URL,
|
|
11
|
+
* an `otp` job's contains the code, an order confirmation's contains a name, an address, and what
|
|
12
|
+
* somebody bought. Projecting it on a read scope would turn "let the dashboard show me the email log"
|
|
13
|
+
* into "let the dashboard sign in as any user who requested a magic link recently", which is a full
|
|
14
|
+
* account takeover reachable from the least privileged credential this capability defines.
|
|
15
|
+
*
|
|
16
|
+
* There is no flag to turn it on and no field that carries a redacted version of it. An operator
|
|
17
|
+
* diagnosing a send needs to know *which template* ran and *what went wrong*, and both are projected.
|
|
18
|
+
* They do not need the variables, and the one case where they would — reproducing a render — is
|
|
19
|
+
* reachable from the adopter's own database, where the audit trail is not a substitute for authority.
|
|
20
|
+
*
|
|
21
|
+
* ## The list masks the recipient; the detail does not
|
|
22
|
+
*
|
|
23
|
+
* `toAddress` is personal data on its own. The list is the bulk surface — a hundred rows a request,
|
|
24
|
+
* paged, is precisely how a compromised credential turns a job log into a customer address book — so it
|
|
25
|
+
* carries a masked address: enough for an operator to recognize the row they are looking for, and
|
|
26
|
+
* useless for harvesting. The **detail** route returns the whole address, one job at a time, with an
|
|
27
|
+
* audit event naming that job.
|
|
28
|
+
*
|
|
29
|
+
* This is a bulk-harvest control, not anonymization, and it is not sold as one. `ad***@example.com`
|
|
30
|
+
* identifies a person to anyone who already knows them. What it does is raise the cost of taking the
|
|
31
|
+
* whole list from one request per hundred addresses to one request per address, each individually
|
|
32
|
+
* recorded — which is the difference between an incident nobody can reconstruct and one whose every
|
|
33
|
+
* step is in the trail. The precedent is the same one testers' `resend` and `remove` follow: return the
|
|
34
|
+
* id, not the address, and let the audit trail hold what the response does not.
|
|
35
|
+
*
|
|
36
|
+
* The **domain survives masking**, deliberately. It is the field an operator reads a deliverability
|
|
37
|
+
* problem off — every failure landing on one provider is the diagnosis — and it names an organization
|
|
38
|
+
* rather than a person.
|
|
39
|
+
*
|
|
40
|
+
* The suppression list is the deliberate exception: an address *is* the record there, so masking it
|
|
41
|
+
* would leave a list of blocks nobody could act on. That is exactly why reading it is its own scope.
|
|
42
|
+
*
|
|
43
|
+
* ## Structural on the list, rendered on the detail
|
|
44
|
+
*
|
|
45
|
+
* The line the list holds is not "less data" — it is *kind* of data. `template`, `category`, `mode`,
|
|
46
|
+
* `bounceType` and `locale` each name what a message was, and none of them carries a character of what
|
|
47
|
+
* it said or of who read it, so a hundred of them in one response is a hundred facts about this
|
|
48
|
+
* project rather than a hundred facts about people. `subject` is the other kind. It is rendered copy,
|
|
49
|
+
* it routinely names the recipient's own order or their own document, and it stays beside the whole
|
|
50
|
+
* address on the detail route, where the disclosure is one job at a time and the audit trail names it.
|
|
51
|
+
*
|
|
52
|
+
* `locale` earns the list on exactly that test. "Why is half this account getting English" is a
|
|
53
|
+
* question about a page of rows, and answering it through the detail route means a hundred audited
|
|
54
|
+
* disclosures of a hundred addresses to render one column.
|
|
55
|
+
*/
|
|
56
|
+
/**
|
|
57
|
+
* Mask a recipient for the list.
|
|
58
|
+
*
|
|
59
|
+
* Two characters of the local part survive, then the domain in full. Anything that does not parse as
|
|
60
|
+
* `local@domain` collapses to `***` rather than being echoed — a row whose address is malformed is
|
|
61
|
+
* usually a row whose address came from somewhere unexpected, and passing it through unchanged is how
|
|
62
|
+
* the one value the mask exists for escapes it.
|
|
63
|
+
*/
|
|
64
|
+
export declare function maskAddress(address: string): string;
|
|
65
|
+
/**
|
|
66
|
+
* ## The field lists live in `responses.ts`
|
|
67
|
+
*
|
|
68
|
+
* Every view type below is `z.output` of the Zod object there, so there is one declaration of what a
|
|
69
|
+
* client receives rather than an interface here and a hand-written mirror of it in every management
|
|
70
|
+
* client. A field added to one and not the other does not compile.
|
|
71
|
+
*/
|
|
72
|
+
/** Project one job for the list. */
|
|
73
|
+
export declare function jobListView(job: EmailJob): EmailJobListItem;
|
|
74
|
+
/** Project one job in full. */
|
|
75
|
+
export declare function jobDetailView(job: EmailJob): EmailJobDetail;
|
|
76
|
+
/** Project one suppression row, resolving `active` against `now`. */
|
|
77
|
+
export declare function suppressionView(row: EmailSuppression, now: Date): EmailSuppressionView;
|
|
78
|
+
//# sourceMappingURL=view.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/http/view.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED;;;;;;GAMG;AAEH,oCAAoC;AACpC,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,gBAAgB,CAiB3D;AAED,+BAA+B;AAC/B,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,cAAc,CAiB3D;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,IAAI,GAAG,oBAAoB,CAatF"}
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
//#region src/http/view.ts
|
|
2
|
+
/**
|
|
3
|
+
* What a management client is allowed to see. Nothing in this package ever returns a raw row.
|
|
4
|
+
*
|
|
5
|
+
* ## `payload` is never projected. Anywhere.
|
|
6
|
+
*
|
|
7
|
+
* `EmailJob.payload` holds the template's input variables, and that is not merely "often PII" — it is
|
|
8
|
+
* the most sensitive column this capability owns. A `magicLink` job's payload contains the sign-in URL,
|
|
9
|
+
* an `otp` job's contains the code, an order confirmation's contains a name, an address, and what
|
|
10
|
+
* somebody bought. Projecting it on a read scope would turn "let the dashboard show me the email log"
|
|
11
|
+
* into "let the dashboard sign in as any user who requested a magic link recently", which is a full
|
|
12
|
+
* account takeover reachable from the least privileged credential this capability defines.
|
|
13
|
+
*
|
|
14
|
+
* There is no flag to turn it on and no field that carries a redacted version of it. An operator
|
|
15
|
+
* diagnosing a send needs to know *which template* ran and *what went wrong*, and both are projected.
|
|
16
|
+
* They do not need the variables, and the one case where they would — reproducing a render — is
|
|
17
|
+
* reachable from the adopter's own database, where the audit trail is not a substitute for authority.
|
|
18
|
+
*
|
|
19
|
+
* ## The list masks the recipient; the detail does not
|
|
20
|
+
*
|
|
21
|
+
* `toAddress` is personal data on its own. The list is the bulk surface — a hundred rows a request,
|
|
22
|
+
* paged, is precisely how a compromised credential turns a job log into a customer address book — so it
|
|
23
|
+
* carries a masked address: enough for an operator to recognize the row they are looking for, and
|
|
24
|
+
* useless for harvesting. The **detail** route returns the whole address, one job at a time, with an
|
|
25
|
+
* audit event naming that job.
|
|
26
|
+
*
|
|
27
|
+
* This is a bulk-harvest control, not anonymization, and it is not sold as one. `ad***@example.com`
|
|
28
|
+
* identifies a person to anyone who already knows them. What it does is raise the cost of taking the
|
|
29
|
+
* whole list from one request per hundred addresses to one request per address, each individually
|
|
30
|
+
* recorded — which is the difference between an incident nobody can reconstruct and one whose every
|
|
31
|
+
* step is in the trail. The precedent is the same one testers' `resend` and `remove` follow: return the
|
|
32
|
+
* id, not the address, and let the audit trail hold what the response does not.
|
|
33
|
+
*
|
|
34
|
+
* The **domain survives masking**, deliberately. It is the field an operator reads a deliverability
|
|
35
|
+
* problem off — every failure landing on one provider is the diagnosis — and it names an organization
|
|
36
|
+
* rather than a person.
|
|
37
|
+
*
|
|
38
|
+
* The suppression list is the deliberate exception: an address *is* the record there, so masking it
|
|
39
|
+
* would leave a list of blocks nobody could act on. That is exactly why reading it is its own scope.
|
|
40
|
+
*
|
|
41
|
+
* ## Structural on the list, rendered on the detail
|
|
42
|
+
*
|
|
43
|
+
* The line the list holds is not "less data" — it is *kind* of data. `template`, `category`, `mode`,
|
|
44
|
+
* `bounceType` and `locale` each name what a message was, and none of them carries a character of what
|
|
45
|
+
* it said or of who read it, so a hundred of them in one response is a hundred facts about this
|
|
46
|
+
* project rather than a hundred facts about people. `subject` is the other kind. It is rendered copy,
|
|
47
|
+
* it routinely names the recipient's own order or their own document, and it stays beside the whole
|
|
48
|
+
* address on the detail route, where the disclosure is one job at a time and the audit trail names it.
|
|
49
|
+
*
|
|
50
|
+
* `locale` earns the list on exactly that test. "Why is half this account getting English" is a
|
|
51
|
+
* question about a page of rows, and answering it through the detail route means a hundred audited
|
|
52
|
+
* disclosures of a hundred addresses to render one column.
|
|
53
|
+
*/
|
|
54
|
+
/**
|
|
55
|
+
* Mask a recipient for the list.
|
|
56
|
+
*
|
|
57
|
+
* Two characters of the local part survive, then the domain in full. Anything that does not parse as
|
|
58
|
+
* `local@domain` collapses to `***` rather than being echoed — a row whose address is malformed is
|
|
59
|
+
* usually a row whose address came from somewhere unexpected, and passing it through unchanged is how
|
|
60
|
+
* the one value the mask exists for escapes it.
|
|
61
|
+
*/
|
|
62
|
+
function maskAddress(address) {
|
|
63
|
+
const at = address.lastIndexOf("@");
|
|
64
|
+
if (at <= 0 || at === address.length - 1) return "***";
|
|
65
|
+
const local = address.slice(0, at);
|
|
66
|
+
const domain = address.slice(at + 1);
|
|
67
|
+
return `${local.slice(0, 2)}***@${domain}`;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* ## The field lists live in `responses.ts`
|
|
71
|
+
*
|
|
72
|
+
* Every view type below is `z.output` of the Zod object there, so there is one declaration of what a
|
|
73
|
+
* client receives rather than an interface here and a hand-written mirror of it in every management
|
|
74
|
+
* client. A field added to one and not the other does not compile.
|
|
75
|
+
*/
|
|
76
|
+
/** Project one job for the list. */
|
|
77
|
+
function jobListView(job) {
|
|
78
|
+
return {
|
|
79
|
+
id: job.id,
|
|
80
|
+
recipient: maskAddress(job.toAddress),
|
|
81
|
+
template: job.template,
|
|
82
|
+
category: job.category,
|
|
83
|
+
locale: job.locale ?? null,
|
|
84
|
+
status: job.status,
|
|
85
|
+
mode: job.mode,
|
|
86
|
+
attempts: job.attempts,
|
|
87
|
+
campaignId: job.campaignId ?? null,
|
|
88
|
+
bounceType: job.bounceType ?? null,
|
|
89
|
+
failed: Boolean(job.error),
|
|
90
|
+
sendAt: job.sendAt.toISOString(),
|
|
91
|
+
createdAt: job.createdAt.toISOString(),
|
|
92
|
+
sentAt: job.sentAt ? job.sentAt.toISOString() : null
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
/** Project one job in full. */
|
|
96
|
+
function jobDetailView(job) {
|
|
97
|
+
const { recipient: _masked, failed: _failed, ...common } = jobListView(job);
|
|
98
|
+
return {
|
|
99
|
+
...common,
|
|
100
|
+
toAddress: job.toAddress,
|
|
101
|
+
subject: job.subject,
|
|
102
|
+
fromAddress: job.fromAddress,
|
|
103
|
+
fromName: job.fromName,
|
|
104
|
+
messageId: job.messageId ?? null,
|
|
105
|
+
error: job.error ?? null,
|
|
106
|
+
bounceCode: job.bounceCode ?? null,
|
|
107
|
+
timezone: job.timezone ?? null,
|
|
108
|
+
localTime: job.localTime ?? null,
|
|
109
|
+
openTracking: job.openTracking,
|
|
110
|
+
clickTracking: job.clickTracking,
|
|
111
|
+
updatedAt: job.updatedAt.toISOString()
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
/** Project one suppression row, resolving `active` against `now`. */
|
|
115
|
+
function suppressionView(row, now) {
|
|
116
|
+
const expiresAt = row.expiresAt ?? null;
|
|
117
|
+
return {
|
|
118
|
+
id: row.id,
|
|
119
|
+
email: row.email,
|
|
120
|
+
reason: row.reason,
|
|
121
|
+
environment: row.environment ?? null,
|
|
122
|
+
jobId: row.jobId ?? null,
|
|
123
|
+
detail: row.detail ?? null,
|
|
124
|
+
createdAt: row.createdAt.toISOString(),
|
|
125
|
+
expiresAt: expiresAt ? expiresAt.toISOString() : null,
|
|
126
|
+
active: expiresAt === null || expiresAt.getTime() > now.getTime()
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
//#endregion
|
|
130
|
+
export { jobDetailView, jobListView, maskAddress, suppressionView };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The package entrypoint — the surface `pithy add email` wires into `pithy.config.ts`. Deliberately
|
|
3
|
+
* narrow: the capability factory plus the enqueue API and the types an app needs to send mail. Every
|
|
4
|
+
* other module is imported by deep path (`@pithy-sh/email/src/...`); this is the documented contract,
|
|
5
|
+
* not a barrel over the package.
|
|
6
|
+
*/
|
|
7
|
+
export { type CampaignStats, campaignStats } from "./analytics";
|
|
8
|
+
export { type EmailCapability, type EmailConfigInput, email, isEmailCapability } from "./capability";
|
|
9
|
+
export type { EmailKind, SuppressionReason } from "./data/enums";
|
|
10
|
+
export type { EmailSuppressionDatabase } from "./data/tables";
|
|
11
|
+
export { EMAIL_CONTROL_PLANE_SCOPES, EMAIL_JOBS_READ_SCOPE, EMAIL_JOBS_RETRY_SCOPE, EMAIL_SUPPRESSIONS_DELETE_SCOPE, EMAIL_SUPPRESSIONS_READ_SCOPE, EMAIL_SUPPRESSIONS_WRITE_SCOPE, } from "./http/guards";
|
|
12
|
+
/**
|
|
13
|
+
* Has this template already gone to this person (pithy-sh/pithy#354).
|
|
14
|
+
*
|
|
15
|
+
* Exported for the same reason the suppression readers are: **it is the adopter's database**, and the
|
|
16
|
+
* alternative to publishing this read is every adopter querying `pithy_email_jobs` through the handle
|
|
17
|
+
* `emailDatabase(d1)` already hands them — a second definition of this capability's schema in somebody
|
|
18
|
+
* else's repository, drifting in whichever direction nobody is looking.
|
|
19
|
+
*
|
|
20
|
+
* A notice that must not repeat, and must be corrected if what it announced stops being true, is the
|
|
21
|
+
* caller this exists for. Do not answer it with a column of your own: a flag saying "we sent it" is a
|
|
22
|
+
* second answer to a question this table already holds the first of, and the two disagree the first time
|
|
23
|
+
* a send fails after the flag is written.
|
|
24
|
+
*/
|
|
25
|
+
export { type SentFilter, type SentLog, SentSummary, sentSince } from "./jobs/read";
|
|
26
|
+
export { type EnqueueInput, type EnqueueResult, enqueueEmail } from "./send/enqueue";
|
|
27
|
+
export { composedEmail, enqueueFromEnv } from "./send/fromComposition";
|
|
28
|
+
/**
|
|
29
|
+
* The suppression list, for the adopter who wants to look (pithy-sh/pithy#355).
|
|
30
|
+
*
|
|
31
|
+
* Nobody needs these to be protected — `enqueue` consults the list on its own and `runSend` refuses a
|
|
32
|
+
* blocked recipient regardless. They are here because **it is the adopter's database**: an operator
|
|
33
|
+
* un-suppressing an address a customer has fixed, a support screen explaining why a letter did not go,
|
|
34
|
+
* a report of who a notice could not reach. Pair them with `EmailCapability.suppressions(env)`, which
|
|
35
|
+
* hands back the handle without anybody naming a binding.
|
|
36
|
+
*
|
|
37
|
+
* `blockingSuppression` takes the message's kind, and the kind belongs to the template — read it with
|
|
38
|
+
* `templateKind`, never type a literal. A restated `"transactional"` is a claim about somebody else's
|
|
39
|
+
* template, and it is the claim that starts withholding invitations from people who unsubscribed from
|
|
40
|
+
* a newsletter.
|
|
41
|
+
*/
|
|
42
|
+
export { blockingSuppression, listSuppressions, type SuppressionListFilter, type SuppressionPage, suppress, suppressionBlocks, unsuppress, } from "./send/suppression";
|
|
43
|
+
export { listTemplates, templateKind } from "./templates/engine";
|
|
44
|
+
export { OperationalNoticePayload } from "./templates/registry";
|
|
45
|
+
export { NoticeSeverity } from "./templates/severity";
|
|
46
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACrG,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjE,YAAY,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAI9D,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,EACtB,+BAA+B,EAC/B,6BAA6B,EAC7B,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AACvB;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIrF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACvE;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,QAAQ,EACR,iBAAiB,EACjB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { campaignStats } from "./analytics.js";
|
|
2
|
+
import { blockingSuppression, listSuppressions, suppress, suppressionBlocks, unsuppress } from "./send/suppression.js";
|
|
3
|
+
import { NoticeSeverity } from "./templates/severity.js";
|
|
4
|
+
import { OperationalNoticePayload } from "./templates/registry.js";
|
|
5
|
+
import { listTemplates, templateKind } from "./templates/engine.js";
|
|
6
|
+
import { EMAIL_CONTROL_PLANE_SCOPES, EMAIL_JOBS_READ_SCOPE, EMAIL_JOBS_RETRY_SCOPE, EMAIL_SUPPRESSIONS_DELETE_SCOPE, EMAIL_SUPPRESSIONS_READ_SCOPE, EMAIL_SUPPRESSIONS_WRITE_SCOPE } from "./http/guards.js";
|
|
7
|
+
import { SentSummary, sentSince } from "./jobs/read.js";
|
|
8
|
+
import { enqueueEmail } from "./send/enqueue.js";
|
|
9
|
+
import { email, isEmailCapability } from "./capability.js";
|
|
10
|
+
import { composedEmail, enqueueFromEnv } from "./send/fromComposition.js";
|
|
11
|
+
export { EMAIL_CONTROL_PLANE_SCOPES, EMAIL_JOBS_READ_SCOPE, EMAIL_JOBS_RETRY_SCOPE, EMAIL_SUPPRESSIONS_DELETE_SCOPE, EMAIL_SUPPRESSIONS_READ_SCOPE, EMAIL_SUPPRESSIONS_WRITE_SCOPE, NoticeSeverity, OperationalNoticePayload, SentSummary, blockingSuppression, campaignStats, composedEmail, email, enqueueEmail, enqueueFromEnv, isEmailCapability, listSuppressions, listTemplates, sentSince, suppress, suppressionBlocks, templateKind, unsuppress };
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import type { z } from "zod";
|
|
2
|
+
import { EmailJob } from "../data/emailJob";
|
|
3
|
+
import type { EmailJobStatus } from "../data/enums";
|
|
4
|
+
import type { EmailDatabase } from "../data/tables";
|
|
5
|
+
/**
|
|
6
|
+
* Reading the send log: the queries behind the two `email:jobs:read` routes, and `sentSince` below.
|
|
7
|
+
*
|
|
8
|
+
* The two are different questions and deliberately not one function. The routes serve an operator
|
|
9
|
+
* walking the log — every job, newest first, filtered by status, paged, and gated by a control-plane
|
|
10
|
+
* scope. `sentSince` answers a single question for the adopter's own code, in their own Worker, about a
|
|
11
|
+
* message they are about to send: has this one already gone out. It is not exposed over HTTP, because
|
|
12
|
+
* nothing calls it over HTTP — see its own note.
|
|
13
|
+
*
|
|
14
|
+
* **Keyset pagination, never offset.** `pithy_email_jobs` is written to on every single send, which
|
|
15
|
+
* makes it the worst possible table to page with `OFFSET`: a row inserted at the head while somebody is
|
|
16
|
+
* on page two pushes one row from page one down, so they see it twice and miss another by luck. The
|
|
17
|
+
* cursor names the last row's `(createdAt, id)` position, so the next page starts exactly where the
|
|
18
|
+
* previous ended whatever arrived in between. The helper is core's — one implementation, one decode,
|
|
19
|
+
* one definition of what a malformed cursor means.
|
|
20
|
+
*
|
|
21
|
+
* `createdAt` is the sort key rather than `sendAt`: a scheduled job's `sendAt` is a *future* time that a
|
|
22
|
+
* retry then moves, so ordering on it would shuffle rows around under a reader for reasons that have
|
|
23
|
+
* nothing to do with when anything happened. `createdAt` never moves.
|
|
24
|
+
*
|
|
25
|
+
* Rows are decoded through `EmailJob.parse` before they leave this module, so callers get Dates and
|
|
26
|
+
* booleans rather than ms-epochs and `0|1` — and a corrupt row fails here rather than three layers up.
|
|
27
|
+
*/
|
|
28
|
+
/** What the list filters and pages by. */
|
|
29
|
+
export interface JobListFilter {
|
|
30
|
+
/** One lifecycle state, or every state when absent. */
|
|
31
|
+
status?: EmailJobStatus;
|
|
32
|
+
/** The previous page's `nextCursor`. A malformed one is a first page. */
|
|
33
|
+
cursor?: string;
|
|
34
|
+
/** How many rows to return, clamped into range. */
|
|
35
|
+
limit?: number;
|
|
36
|
+
}
|
|
37
|
+
/** One page of the send log. */
|
|
38
|
+
export interface JobPage {
|
|
39
|
+
/** The jobs, newest first. */
|
|
40
|
+
items: EmailJob[];
|
|
41
|
+
/** Where the next page starts, or null at the end of the list. */
|
|
42
|
+
nextCursor: string | null;
|
|
43
|
+
}
|
|
44
|
+
/** One page of jobs, newest first, optionally filtered to one status. */
|
|
45
|
+
export declare function listJobs(db: EmailDatabase, filter: JobListFilter): Promise<JobPage>;
|
|
46
|
+
/** One job by id, or undefined. The caller decides what a miss means. */
|
|
47
|
+
export declare function getJob(db: EmailDatabase, jobId: string): Promise<EmailJob | undefined>;
|
|
48
|
+
/**
|
|
49
|
+
* ## `sentSince` — has this message already gone out
|
|
50
|
+
*
|
|
51
|
+
* The narrow read, for the caller deciding whether to send. A transactional notice that must not repeat,
|
|
52
|
+
* and must be *corrected* if the thing it announced stops being true, cannot be decided from a flag of
|
|
53
|
+
* the caller's own: a `cancellationNoticeSentAt` column is a second answer to a question this table
|
|
54
|
+
* already holds the first of, and the two disagree the first time a send fails after the flag is
|
|
55
|
+
* written. `pithy_email_jobs` is the record; this is the read over it, so nobody has to define its shape
|
|
56
|
+
* a second time in their own repository.
|
|
57
|
+
*
|
|
58
|
+
* ## Two axes, because a template is not always one message
|
|
59
|
+
*
|
|
60
|
+
* It was `(to, template)` alone, and that could not finish its only intended consumer (pithy-sh/pithy#382).
|
|
61
|
+
* Six account notices ride one `operationalNotice` to the same addresses, so the template id does not
|
|
62
|
+
* separate them; `correlation` is the enqueue-side discriminator that does. See {@link SentSubject} for
|
|
63
|
+
* why the two are a union and not three optional fields.
|
|
64
|
+
*
|
|
65
|
+
* **The direction of the failure is why this was worth a column.** The dashboard uses the answer
|
|
66
|
+
* *positively*: the correction letter goes out only when the letter it corrects already did. An
|
|
67
|
+
* under-report there sends nothing at all — it withholds the correction from somebody holding a letter
|
|
68
|
+
* that has stopped being true. That is silence, to the one person owed the message, and silence is the
|
|
69
|
+
* failure nobody finds in production.
|
|
70
|
+
*
|
|
71
|
+
* ## Four columns, and every other one is a deliberate no
|
|
72
|
+
*
|
|
73
|
+
* `SentSummary` is `EmailJob.pick(…)`, so the columns it carries are the columns it selects and a
|
|
74
|
+
* projection cannot leak one it never loaded. What is not on it:
|
|
75
|
+
*
|
|
76
|
+
* - **`toAddress`.** The caller passed the address in; handing it back means a read answering a question
|
|
77
|
+
* about one person returns a copy of them in every row, and any log of the result is an address list.
|
|
78
|
+
* - **`payload`.** The sign-in link and the OTP. `view.ts` argues this at length and the argument is the
|
|
79
|
+
* same here, except that this reader is reachable from ordinary application code rather than only from
|
|
80
|
+
* a scoped credential, which makes it stronger rather than weaker.
|
|
81
|
+
* - **`subject`.** Rendered content, and the temptation is specific: it is the only per-row string that
|
|
82
|
+
* distinguishes two messages sharing a template, so a caller needing that discrimination would match
|
|
83
|
+
* on it. That match breaks on a copy edit, silently, in the direction of sending again. Discriminating
|
|
84
|
+
* two notices was the enqueue side's problem and now has an enqueue-side answer — `correlation`
|
|
85
|
+
* (#382) — rather than a rendered string exported to be string-matched.
|
|
86
|
+
* - **`messageId`, `error`, `bounceCode`.** The provider's own words. A provider error routinely embeds
|
|
87
|
+
* the recipient, which is why the list view carries `failed` rather than the text.
|
|
88
|
+
*
|
|
89
|
+
* `status` rather than a boolean, because the statuses are the answer: a `failed` or `suppressed` row is
|
|
90
|
+
* an email nobody read, and a reader that collapsed the log to "yes" would treat it as one they did.
|
|
91
|
+
*
|
|
92
|
+
* ## Bounded, and it says when the bound bit
|
|
93
|
+
*
|
|
94
|
+
* The log is append-only and unbounded by nature, so the read is capped — and a cap that silently
|
|
95
|
+
* truncates is the failure mode, not the bound. `truncated` says the cap was reached, the same word
|
|
96
|
+
* `@pithy-sh/auth`'s bounded sub-lists use. A caller counting rows must read it; a caller asking only
|
|
97
|
+
* "did anything go out" may ignore it, because a truncated page is still a non-empty one.
|
|
98
|
+
*/
|
|
99
|
+
/**
|
|
100
|
+
* One job as the send-decision reader sees it: the handle, the outcome, and the two instants.
|
|
101
|
+
*
|
|
102
|
+
* Derived from `EmailJob` with `.pick()` rather than restated, so the codecs and the field descriptions
|
|
103
|
+
* come from the one table definition and a column added to the row does not silently appear here.
|
|
104
|
+
* Re-described because `.pick()` builds a new schema and the top-level description does not follow it.
|
|
105
|
+
*/
|
|
106
|
+
export declare const SentSummary: z.ZodObject<{
|
|
107
|
+
id: z.ZodString;
|
|
108
|
+
status: z.ZodEnum<{
|
|
109
|
+
bounced: "bounced";
|
|
110
|
+
canceled: "canceled";
|
|
111
|
+
failed: "failed";
|
|
112
|
+
pending: "pending";
|
|
113
|
+
scheduled: "scheduled";
|
|
114
|
+
sending: "sending";
|
|
115
|
+
sent: "sent";
|
|
116
|
+
suppressed: "suppressed";
|
|
117
|
+
undispatched: "undispatched";
|
|
118
|
+
}>;
|
|
119
|
+
createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
|
|
120
|
+
sentAt: z.ZodOptional<z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>>;
|
|
121
|
+
}, z.core.$strip>;
|
|
122
|
+
export type SentSummary = z.output<typeof SentSummary>;
|
|
123
|
+
/**
|
|
124
|
+
* Which messages are being asked about — one of the two indexed axes, and the type admits no third
|
|
125
|
+
* answer.
|
|
126
|
+
*
|
|
127
|
+
* **`(to, template)`** is the original question: has this template already gone to this person. It runs
|
|
128
|
+
* on `(recipientKey, template, createdAt)`.
|
|
129
|
+
*
|
|
130
|
+
* **`correlation`** is the question a template carrying more than one kind of message needs
|
|
131
|
+
* (pithy-sh/pithy#382): has *this thing* already been said. Six account notices ride one
|
|
132
|
+
* `operationalNotice` to the same addresses, so the template id cannot separate them and the address is
|
|
133
|
+
* a proxy for the account only while one person belongs to one account. It runs on
|
|
134
|
+
* `(correlation, createdAt)`.
|
|
135
|
+
*
|
|
136
|
+
* Written as a union rather than three optional fields because the shape a union forbids is the one that
|
|
137
|
+
* matters: a filter naming *neither* axis is an unbounded scan of every email the project ever queued,
|
|
138
|
+
* asked on the path that decides whether to send. It cannot be constructed. Both axes together is
|
|
139
|
+
* allowed and narrows further.
|
|
140
|
+
*/
|
|
141
|
+
export type SentSubject = {
|
|
142
|
+
/** The recipient. Matched under `normalizeAddress`, the same rule the row was keyed under. */
|
|
143
|
+
readonly to: string;
|
|
144
|
+
/** The template id, exactly. */
|
|
145
|
+
readonly template: string;
|
|
146
|
+
/** Optionally narrower still: which of this template's messages. */
|
|
147
|
+
readonly correlation?: string;
|
|
148
|
+
} | {
|
|
149
|
+
/** What the message was about, exactly as the enqueue stated it. */
|
|
150
|
+
readonly correlation: string;
|
|
151
|
+
/** Optional here — the correlation already bounds the read. */
|
|
152
|
+
readonly to?: string;
|
|
153
|
+
/** Optional here — the correlation already bounds the read. */
|
|
154
|
+
readonly template?: string;
|
|
155
|
+
};
|
|
156
|
+
/** What `sentSince` asks: a subject, a floor, and a bound. The bound is the only one clamped. */
|
|
157
|
+
export type SentFilter = SentSubject & {
|
|
158
|
+
/**
|
|
159
|
+
* The earliest `createdAt` to consider, inclusive.
|
|
160
|
+
*
|
|
161
|
+
* Required, with no default. An unbounded question against an append-only send log is a table scan
|
|
162
|
+
* whose cost grows with the project's age, asked on the path that decides whether to send — and a
|
|
163
|
+
* default would be this module choosing how far back "already" reaches, which is the caller's
|
|
164
|
+
* decision and differs per notice.
|
|
165
|
+
*/
|
|
166
|
+
readonly since: Date;
|
|
167
|
+
/** How many rows to return, clamped into range. The default is `DEFAULT_PAGE_SIZE`. */
|
|
168
|
+
readonly limit?: number;
|
|
169
|
+
};
|
|
170
|
+
/** What went out, and whether the bound cut the answer short. */
|
|
171
|
+
export interface SentLog {
|
|
172
|
+
/** The matching jobs, newest first, at most the clamped limit. */
|
|
173
|
+
items: SentSummary[];
|
|
174
|
+
/** True when more rows matched than the limit allowed. A count taken off `items` is wrong when this is set. */
|
|
175
|
+
truncated: boolean;
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Every job matching one subject since an instant, newest first.
|
|
179
|
+
*
|
|
180
|
+
* The subject is `(to, template)`, or a `correlation`, or both — see {@link SentSubject}. Neither is not
|
|
181
|
+
* a subject, and the type will not build one.
|
|
182
|
+
*
|
|
183
|
+
* **A row that will not parse throws.** It is tempting to skip it and carry on, and it is wrong here in
|
|
184
|
+
* a way it is not on a listing: this reader's answer decides whether a message goes out. A skipped row
|
|
185
|
+
* is reported as an email that never went, which means a duplicate send — or, where the caller is
|
|
186
|
+
* looking for who to send a *correction* to, a correction withheld from exactly the person owed one.
|
|
187
|
+
* Both failures are silent and neither is recoverable after the fact, so a row this schema cannot read
|
|
188
|
+
* stops the decision instead of quietly biasing it.
|
|
189
|
+
*/
|
|
190
|
+
export declare function sentSince(db: EmailDatabase, filter: SentFilter): Promise<SentLog>;
|
|
191
|
+
//# sourceMappingURL=read.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/jobs/read.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gCAAgC;AAChC,MAAM,WAAW,OAAO;IACtB,8BAA8B;IAC9B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAgBD,yEAAyE;AACzE,wBAAsB,QAAQ,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAuBzF;AAED,yEAAyE;AACzE,wBAAsB,MAAM,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAG5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;iBAEvB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,GACD;IACE,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEN,iGAAiG;AACjG,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,+GAA+G;IAC/G,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAqCvF"}
|