@hogsend/engine 0.63.0 → 0.64.0
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/package.json +13 -12
- package/src/env.ts +23 -0
- package/src/index.ts +17 -0
- package/src/journeys/journey-boundary.ts +8 -0
- package/src/lib/attachments.ts +81 -0
- package/src/lib/domain-status.return-path.test.ts +68 -0
- package/src/lib/domain-status.ts +19 -0
- package/src/lib/email-provider-boot.hogsend.test.ts +48 -0
- package/src/lib/email-provider-boot.test.ts +33 -0
- package/src/lib/email-providers-from-env.hogsend.test.ts +110 -0
- package/src/lib/email-providers-from-env.test.ts +52 -0
- package/src/lib/email-providers-from-env.ts +67 -0
- package/src/lib/email-service-types.ts +11 -0
- package/src/lib/email.ts +17 -0
- package/src/lib/mailer-bounce-idempotency.test.ts +469 -0
- package/src/lib/mailer-rejected.test.ts +229 -0
- package/src/lib/mailer-replied.test.ts +379 -0
- package/src/lib/mailer.ts +359 -24
- package/src/lib/outbound.ts +35 -0
- package/src/lib/sending-domain-guidance.test.ts +99 -0
- package/src/lib/sending-domain-guidance.ts +84 -0
- package/src/lib/tracked-attachments.test.ts +376 -0
- package/src/lib/tracked-idempotency-header.test.ts +437 -0
- package/src/lib/tracked.ts +116 -4
- package/src/lib/tracking-event-names.ts +9 -0
- package/src/lib/webhook-signing.ts +7 -0
- package/src/routes/admin/domain-conflict.test.ts +188 -0
- package/src/routes/admin/domain-return-path.test.ts +274 -0
- package/src/routes/admin/domain.ts +214 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.64.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"dependencies": {
|
|
33
33
|
"@hatchet-dev/typescript-sdk": "^1.22.3",
|
|
34
34
|
"@hono/node-server": "^2.0.4",
|
|
35
|
-
"@hono/zod-openapi": "
|
|
35
|
+
"@hono/zod-openapi": "1.4.0",
|
|
36
36
|
"@openrouter/ai-sdk-provider": "^2.9.1",
|
|
37
37
|
"@scalar/hono-api-reference": "^0.10.19",
|
|
38
38
|
"@t3-oss/env-core": "^0.13.11",
|
|
@@ -53,18 +53,19 @@
|
|
|
53
53
|
"svix": "^1.95.1",
|
|
54
54
|
"winston": "^3.19.0",
|
|
55
55
|
"zod": "^4.4.3",
|
|
56
|
-
"@hogsend/attribution": "^0.
|
|
57
|
-
"@hogsend/core": "^0.
|
|
58
|
-
"@hogsend/db": "^0.
|
|
59
|
-
"@hogsend/email": "^0.
|
|
60
|
-
"@hogsend/plugin-posthog": "^0.
|
|
61
|
-
"@hogsend/plugin-resend": "^0.
|
|
62
|
-
"@hogsend/sms": "^0.
|
|
56
|
+
"@hogsend/attribution": "^0.64.0",
|
|
57
|
+
"@hogsend/core": "^0.64.0",
|
|
58
|
+
"@hogsend/db": "^0.64.0",
|
|
59
|
+
"@hogsend/email": "^0.64.0",
|
|
60
|
+
"@hogsend/plugin-posthog": "^0.64.0",
|
|
61
|
+
"@hogsend/plugin-resend": "^0.64.0",
|
|
62
|
+
"@hogsend/sms": "^0.64.0"
|
|
63
63
|
},
|
|
64
64
|
"optionalDependencies": {
|
|
65
|
-
"@hogsend/plugin-apollo": "^0.
|
|
66
|
-
"@hogsend/plugin-
|
|
67
|
-
"@hogsend/plugin-
|
|
65
|
+
"@hogsend/plugin-apollo": "^0.64.0",
|
|
66
|
+
"@hogsend/plugin-hogsend": "^0.64.0",
|
|
67
|
+
"@hogsend/plugin-postmark": "^0.64.0",
|
|
68
|
+
"@hogsend/plugin-twilio": "^0.64.0"
|
|
68
69
|
},
|
|
69
70
|
"devDependencies": {
|
|
70
71
|
"@types/node": "^22.15.3",
|
package/src/env.ts
CHANGED
|
@@ -130,6 +130,29 @@ export const env = createEnv({
|
|
|
130
130
|
POSTMARK_MESSAGE_STREAM: z.string().min(1).optional(),
|
|
131
131
|
POSTMARK_WEBHOOK_USER: z.string().min(1).optional(),
|
|
132
132
|
POSTMARK_WEBHOOK_PASS: z.string().min(1).optional(),
|
|
133
|
+
// --- Hogsend Email (Cloud-only first-party sending; opt-in provider) ---
|
|
134
|
+
// The environment's relay token (`hsrel_…`), minted by Hogsend Cloud at
|
|
135
|
+
// provision time. It is the ONLY credential a tenant instance holds — the
|
|
136
|
+
// AWS credentials never leave the control plane.
|
|
137
|
+
//
|
|
138
|
+
// Its ABSENCE is a mode, not a gap: with no token `@hogsend/plugin-hogsend`
|
|
139
|
+
// is never imported at all, so a self-hosted deploy that will never send
|
|
140
|
+
// through Cloud never touches the package and behaves exactly as before.
|
|
141
|
+
// Present, a preset is built — and like Postmark it NEVER changes the
|
|
142
|
+
// active provider on its own; set EMAIL_PROVIDER=hogsend to activate it.
|
|
143
|
+
HOGSEND_EMAIL_TOKEN: z.string().min(1).optional(),
|
|
144
|
+
// Origin of the Hogsend Cloud control plane the send relay lives on (the
|
|
145
|
+
// provisioner injects its own CLOUD_PUBLIC_URL here). NO default ON
|
|
146
|
+
// PURPOSE: staging and production control planes are different origins, so
|
|
147
|
+
// a guessed default would point a tenant's mail at the wrong one. A token
|
|
148
|
+
// set WITHOUT this is a misconfiguration — the preset warns and skips
|
|
149
|
+
// rather than building a provider aimed at nowhere.
|
|
150
|
+
HOGSEND_EMAIL_RELAY_URL: z.string().url().optional(),
|
|
151
|
+
// HMAC secret the relay signs its status webhooks with. Absent ⇒ the
|
|
152
|
+
// provider FAILS CLOSED: every inbound webhook is rejected before it is
|
|
153
|
+
// parsed, so an unauthenticated status update can never mark a contact
|
|
154
|
+
// bounced. Sending is unaffected; only status updates stop.
|
|
155
|
+
HOGSEND_EMAIL_WEBHOOK_SECRET: z.string().min(1).optional(),
|
|
133
156
|
// --- Base-currency FX lens (optional; docs/groups.md §Base-currency lens) ---
|
|
134
157
|
// The operator's reporting currency. UNSET = the lens is OFF everywhere
|
|
135
158
|
// (zero behavior change): no converted figures, no converted ranking. Set
|
package/src/index.ts
CHANGED
|
@@ -28,7 +28,9 @@ export type {
|
|
|
28
28
|
/** @deprecated Use {@link EmailEvent}. Frozen `event.raw` cast target. */
|
|
29
29
|
LegacyResendWebhookEvent,
|
|
30
30
|
PostHogService,
|
|
31
|
+
ReturnPathState,
|
|
31
32
|
SendResult,
|
|
33
|
+
SetReturnPathInput,
|
|
32
34
|
/** @deprecated Use {@link EmailEvent}. Kept for one minor. */
|
|
33
35
|
WebhookEvent,
|
|
34
36
|
WebhookHandlerMap,
|
|
@@ -306,6 +308,13 @@ export {
|
|
|
306
308
|
} from "./lib/analytics-identity.js";
|
|
307
309
|
export { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
|
|
308
310
|
export { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
|
|
311
|
+
// --- Attachments (engine-side gate + email_sends metadata shape, PRD 17) ---
|
|
312
|
+
export {
|
|
313
|
+
type AttachmentSendMetadata,
|
|
314
|
+
AttachmentsUnsupportedError,
|
|
315
|
+
assertAttachmentsSendable,
|
|
316
|
+
attachmentSendMetadata,
|
|
317
|
+
} from "./lib/attachments.js";
|
|
309
318
|
// --- Auth ---
|
|
310
319
|
export {
|
|
311
320
|
type Auth,
|
|
@@ -708,6 +717,13 @@ export {
|
|
|
708
717
|
SEMANTIC_BURST_DISTINCT_LINKS,
|
|
709
718
|
SEMANTIC_BURST_WINDOW_MS,
|
|
710
719
|
} from "./lib/semantic-click.js";
|
|
720
|
+
// --- Sending-subdomain setup guidance (static; one source for all surfaces) ---
|
|
721
|
+
export {
|
|
722
|
+
exampleSendingSubdomain,
|
|
723
|
+
looksLikeRootDomain,
|
|
724
|
+
SENDING_DOMAIN_GUIDANCE,
|
|
725
|
+
type SendingDomainGuidance,
|
|
726
|
+
} from "./lib/sending-domain-guidance.js";
|
|
711
727
|
// --- SMS ---
|
|
712
728
|
export {
|
|
713
729
|
getSmsService,
|
|
@@ -770,6 +786,7 @@ export {
|
|
|
770
786
|
export {
|
|
771
787
|
EMAIL_LINK_CLICKED,
|
|
772
788
|
EMAIL_OPENED,
|
|
789
|
+
EMAIL_REPLIED,
|
|
773
790
|
LINK_ARRIVED,
|
|
774
791
|
LINK_CLICKED,
|
|
775
792
|
SMS_LINK_CLICKED,
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
|
+
import type { EmailAttachment } from "@hogsend/core";
|
|
2
3
|
|
|
3
4
|
/**
|
|
4
5
|
* The minimal slice of Hatchet's `DurableContext` the boundary needs for its
|
|
@@ -25,6 +26,13 @@ export interface JourneyEmailEffect {
|
|
|
25
26
|
journeyName?: string;
|
|
26
27
|
journeyStateId?: string;
|
|
27
28
|
idempotencyKey?: string;
|
|
29
|
+
/**
|
|
30
|
+
* Neutral attachments (PRD 17), carried so a scoped `services.email`
|
|
31
|
+
* override observes the files a send would carry rather than silently
|
|
32
|
+
* dropping them. Deliberately NOT part of any derived idempotency key —
|
|
33
|
+
* the key stays `kind:anchor:site:template`.
|
|
34
|
+
*/
|
|
35
|
+
attachments?: EmailAttachment[];
|
|
28
36
|
}
|
|
29
37
|
|
|
30
38
|
export interface JourneySmsEffect {
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import type { EmailAttachment, EmailProvider } from "@hogsend/core";
|
|
2
|
+
import { assertValidAttachments, attachmentByteLength } from "@hogsend/core";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Thrown when a send carries attachments but the resolved provider does not
|
|
6
|
+
* declare `capabilities.attachments`. A named class (mirroring
|
|
7
|
+
* `TestModeNoRedirectError`) so callers can branch on it without
|
|
8
|
+
* string-matching the message; the message itself names the provider id AND
|
|
9
|
+
* the capability so an operator reading a log can act on it directly.
|
|
10
|
+
*/
|
|
11
|
+
export class AttachmentsUnsupportedError extends Error {
|
|
12
|
+
readonly code = "attachments_unsupported";
|
|
13
|
+
constructor(readonly providerId: string) {
|
|
14
|
+
super(
|
|
15
|
+
`Email provider "${providerId}" does not declare capabilities.attachments — ` +
|
|
16
|
+
`refusing to send a message without its files. Switch to a provider that ` +
|
|
17
|
+
`carries attachments, or drop the attachments from this send.`,
|
|
18
|
+
);
|
|
19
|
+
this.name = "AttachmentsUnsupportedError";
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* The engine-side attachment gate, run BEFORE any other send work (no DB row,
|
|
25
|
+
* no render, no provider call happens first). Two checks, in order:
|
|
26
|
+
*
|
|
27
|
+
* 1. `assertValidAttachments` — shape/size/count validation. The relay
|
|
28
|
+
* validates too, and that is deliberate defence in depth rather than
|
|
29
|
+
* duplication: a Resend or Postmark send never passes through the relay at
|
|
30
|
+
* all, so for those providers THIS is the only gate before the wire.
|
|
31
|
+
*
|
|
32
|
+
* 2. The capability gate — throw unless the provider DECLARES
|
|
33
|
+
* `capabilities.attachments === true`. The quiet alternative (send the
|
|
34
|
+
* message, drop the files) is genuinely tempting and genuinely wrong: a
|
|
35
|
+
* receipt that arrives without its invoice looks *delivered* from every
|
|
36
|
+
* dashboard, from `email_sends`, and from the provider's own logs — nobody
|
|
37
|
+
* discovers it until the customer does. Absence of the flag is NOT consent
|
|
38
|
+
* (same rule as `consumesIdempotencyKey`): an absent or `false` flag means
|
|
39
|
+
* the provider cannot carry the files, so the send must fail loudly here,
|
|
40
|
+
* before anything is written or dispatched.
|
|
41
|
+
*/
|
|
42
|
+
export function assertAttachmentsSendable(
|
|
43
|
+
provider: EmailProvider,
|
|
44
|
+
attachments: EmailAttachment[],
|
|
45
|
+
): void {
|
|
46
|
+
assertValidAttachments(attachments);
|
|
47
|
+
if (provider.capabilities?.attachments !== true) {
|
|
48
|
+
throw new AttachmentsUnsupportedError(provider.meta?.id ?? "resend");
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* One recorded metadata entry per attachment on the `email_sends` row:
|
|
54
|
+
* filename, raw byte size, and content type when declared.
|
|
55
|
+
*/
|
|
56
|
+
export interface AttachmentSendMetadata {
|
|
57
|
+
filename: string;
|
|
58
|
+
sizeBytes: number;
|
|
59
|
+
contentType?: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* What `email_sends.metadata.attachments` records: that the message HAD
|
|
64
|
+
* attachments — their filenames, raw sizes, and content types. NEVER the
|
|
65
|
+
* content itself. Storing customer invoices indefinitely is a data-protection
|
|
66
|
+
* decision nobody has made, and quietly making it here by persisting bytes
|
|
67
|
+
* would be the wrong default. Size comes from `attachmentByteLength` (raw
|
|
68
|
+
* bytes, decoded for `{ base64 }` content) so the recorded number matches the
|
|
69
|
+
* one the size cap enforces.
|
|
70
|
+
*/
|
|
71
|
+
export function attachmentSendMetadata(
|
|
72
|
+
attachments: EmailAttachment[],
|
|
73
|
+
): AttachmentSendMetadata[] {
|
|
74
|
+
return attachments.map((attachment) => ({
|
|
75
|
+
filename: attachment.filename,
|
|
76
|
+
sizeBytes: attachmentByteLength(attachment),
|
|
77
|
+
...(attachment.contentType !== undefined
|
|
78
|
+
? { contentType: attachment.contentType }
|
|
79
|
+
: {}),
|
|
80
|
+
}));
|
|
81
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import { test } from "node:test";
|
|
3
|
+
import type { DomainsCapability, EmailProvider } from "@hogsend/core";
|
|
4
|
+
import { createDomainStatusService } from "./domain-status.js";
|
|
5
|
+
|
|
6
|
+
// `EngineDomainStatus.returnPathSupported` is the discovery bit Studio/CLI key
|
|
7
|
+
// the return-path control off (PRD 20 EARS: when the capability has no
|
|
8
|
+
// `setReturnPath`, the upgrade is reported unavailable — never rendered as a
|
|
9
|
+
// dead control). Held here against the REAL service, since the admin-route
|
|
10
|
+
// tests run on a fake status service.
|
|
11
|
+
|
|
12
|
+
const noopLogger = {
|
|
13
|
+
info() {},
|
|
14
|
+
warn() {},
|
|
15
|
+
error() {},
|
|
16
|
+
debug() {},
|
|
17
|
+
} as never;
|
|
18
|
+
|
|
19
|
+
const STATUS = {
|
|
20
|
+
domain: "acme.test",
|
|
21
|
+
state: "verified",
|
|
22
|
+
records: [],
|
|
23
|
+
providerId: "fake",
|
|
24
|
+
checkedAt: "2026-08-11T00:00:00.000Z",
|
|
25
|
+
} as const;
|
|
26
|
+
|
|
27
|
+
function makeService(domains?: DomainsCapability) {
|
|
28
|
+
const provider = {
|
|
29
|
+
meta: { id: "fake", name: "Fake" },
|
|
30
|
+
...(domains ? { domains } : {}),
|
|
31
|
+
} as unknown as EmailProvider;
|
|
32
|
+
return createDomainStatusService({
|
|
33
|
+
provider,
|
|
34
|
+
env: { EMAIL_DOMAIN: "acme.test", HOGSEND_TEST_MODE: "false" } as never,
|
|
35
|
+
logger: noopLogger,
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const baseCapability: DomainsCapability = {
|
|
40
|
+
create: async () => ({ ...STATUS, records: [] }),
|
|
41
|
+
get: async () => ({ ...STATUS, records: [] }),
|
|
42
|
+
records: async () => [],
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
test("returnPathSupported is true when the capability has setReturnPath", async () => {
|
|
46
|
+
const service = makeService({
|
|
47
|
+
...baseCapability,
|
|
48
|
+
setReturnPath: async () => ({
|
|
49
|
+
enabled: true,
|
|
50
|
+
mailFromDomain: "send.acme.test",
|
|
51
|
+
status: { ...STATUS, records: [] },
|
|
52
|
+
}),
|
|
53
|
+
});
|
|
54
|
+
const status = await service.getStatus();
|
|
55
|
+
assert.equal(status.returnPathSupported, true);
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
test("returnPathSupported is false when domains exists without it", async () => {
|
|
59
|
+
const status = await makeService(baseCapability).getStatus();
|
|
60
|
+
assert.equal(status.supported, true);
|
|
61
|
+
assert.equal(status.returnPathSupported, false);
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
test("returnPathSupported is false when there is no domains capability", async () => {
|
|
65
|
+
const status = await makeService().getStatus();
|
|
66
|
+
assert.equal(status.supported, false);
|
|
67
|
+
assert.equal(status.returnPathSupported, false);
|
|
68
|
+
});
|
package/src/lib/domain-status.ts
CHANGED
|
@@ -2,6 +2,10 @@ import type { DomainStatus, EmailProvider } from "@hogsend/core";
|
|
|
2
2
|
import type { env as envSchema } from "../env.js";
|
|
3
3
|
import { hostOfFromAddress } from "./from-address.js";
|
|
4
4
|
import type { Logger } from "./logger.js";
|
|
5
|
+
import {
|
|
6
|
+
SENDING_DOMAIN_GUIDANCE,
|
|
7
|
+
type SendingDomainGuidance,
|
|
8
|
+
} from "./sending-domain-guidance.js";
|
|
5
9
|
|
|
6
10
|
/**
|
|
7
11
|
* Per-send test-mode snapshot (PROJECT_SPEC pinned shape).
|
|
@@ -36,9 +40,19 @@ export interface EngineDomainStatus {
|
|
|
36
40
|
providerId: string;
|
|
37
41
|
/** `!!provider.domains` — presence of the capability is the gate. */
|
|
38
42
|
supported: boolean;
|
|
43
|
+
/**
|
|
44
|
+
* Whether `provider.domains.setReturnPath` exists — the branded-return-path
|
|
45
|
+
* upgrade's own gate (PRD 20). Studio/CLI key the toggle off this so a
|
|
46
|
+
* provider without the method gets NO dead control; the POST would 501.
|
|
47
|
+
* Optional in the TYPE only for wire skew (an older engine never sends it,
|
|
48
|
+
* and clients ship separately from engines); this engine always sets it.
|
|
49
|
+
*/
|
|
50
|
+
returnPathSupported?: boolean;
|
|
39
51
|
/** `null` when `!supported || !domain` (the provider is never called then). */
|
|
40
52
|
status: DomainStatus | null;
|
|
41
53
|
testMode: TestModeState;
|
|
54
|
+
/** Static setup advice. Same words in Studio and the CLI, one source. */
|
|
55
|
+
guidance: SendingDomainGuidance;
|
|
42
56
|
}
|
|
43
57
|
|
|
44
58
|
/**
|
|
@@ -180,6 +194,8 @@ export function createDomainStatusService(deps: {
|
|
|
180
194
|
|
|
181
195
|
const providerId = provider.meta?.id ?? "resend";
|
|
182
196
|
const supported = Boolean(provider.domains);
|
|
197
|
+
const returnPathSupported =
|
|
198
|
+
typeof provider.domains?.setReturnPath === "function";
|
|
183
199
|
const domain =
|
|
184
200
|
env.EMAIL_DOMAIN ??
|
|
185
201
|
hostPartOf(env.EMAIL_FROM) ??
|
|
@@ -278,6 +294,7 @@ export function createDomainStatusService(deps: {
|
|
|
278
294
|
domain,
|
|
279
295
|
providerId,
|
|
280
296
|
supported,
|
|
297
|
+
returnPathSupported,
|
|
281
298
|
status,
|
|
282
299
|
testMode: {
|
|
283
300
|
active: false,
|
|
@@ -285,6 +302,8 @@ export function createDomainStatusService(deps: {
|
|
|
285
302
|
redirectTo: null,
|
|
286
303
|
fromOverride: null,
|
|
287
304
|
},
|
|
305
|
+
// Constant advice — no computation, no cache interaction.
|
|
306
|
+
guidance: SENDING_DOMAIN_GUIDANCE,
|
|
288
307
|
};
|
|
289
308
|
cache = { snapshot, fetchedAt: Date.now() };
|
|
290
309
|
const testMode = computeTestMode();
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
|
|
4
|
+
// The positive half of email-provider-boot.test.ts, in its own process because
|
|
5
|
+
// the two need opposite HOGSEND_EMAIL_TOKEN postures at module load (the guarded
|
|
6
|
+
// dynamic import fires at module scope). Together they are the whole contract:
|
|
7
|
+
// token present ⇒ registered and resolvable; token absent ⇒ boot throws.
|
|
8
|
+
//
|
|
9
|
+
// This is the end-to-end wiring proof for the engine side of PRD 10 — env var →
|
|
10
|
+
// guarded import → preset → EmailProviderRegistry → the ACTIVE provider the
|
|
11
|
+
// tracked mailer sends through. No network: the provider is constructed, never
|
|
12
|
+
// called.
|
|
13
|
+
process.env.NODE_ENV ??= "test";
|
|
14
|
+
process.env.LOG_LEVEL ??= "error";
|
|
15
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
16
|
+
process.env.BETTER_AUTH_SECRET ??=
|
|
17
|
+
"test-secret-for-node-test-minimum-32-characters-long";
|
|
18
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
19
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
20
|
+
// Exactly what a provisioned Cloud environment gets — and deliberately NO
|
|
21
|
+
// RESEND_API_KEY, which is the point: a Cloud instance sends with no Resend
|
|
22
|
+
// account anywhere in the picture. Deleted (not assumed absent) so a dev shell
|
|
23
|
+
// that happens to export provider credentials cannot flip the getAll()
|
|
24
|
+
// assertion below.
|
|
25
|
+
delete process.env.RESEND_API_KEY;
|
|
26
|
+
delete process.env.POSTMARK_SERVER_TOKEN;
|
|
27
|
+
process.env.HOGSEND_EMAIL_TOKEN = "hsrel_boot_test_token";
|
|
28
|
+
process.env.HOGSEND_EMAIL_RELAY_URL = "https://cloud.example.com";
|
|
29
|
+
process.env.HOGSEND_EMAIL_WEBHOOK_SECRET = "whsec_boot_test";
|
|
30
|
+
process.env.EMAIL_PROVIDER = "hogsend";
|
|
31
|
+
|
|
32
|
+
const { createHogsendClient } = await import("../container.js");
|
|
33
|
+
|
|
34
|
+
test("EMAIL_PROVIDER=hogsend + a relay token → hogsend is the ACTIVE provider", () => {
|
|
35
|
+
const client = createHogsendClient();
|
|
36
|
+
|
|
37
|
+
assert.equal(client.emailProvider.meta?.id, "hogsend");
|
|
38
|
+
assert.ok(
|
|
39
|
+
client.emailProviders.get("hogsend"),
|
|
40
|
+
"the registry must hold the provider the webhook route dispatches by id",
|
|
41
|
+
);
|
|
42
|
+
// No Resend key was set, so nothing else is registered — a Cloud instance
|
|
43
|
+
// boots and sends with no Resend account at all.
|
|
44
|
+
assert.deepEqual(
|
|
45
|
+
client.emailProviders.getAll().map((p) => p.meta?.id),
|
|
46
|
+
["hogsend"],
|
|
47
|
+
);
|
|
48
|
+
});
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
|
|
4
|
+
// EMAIL_PROVIDER=hogsend with the package/token absent must fail LOUDLY at boot,
|
|
5
|
+
// exactly like any other unresolvable id. Nothing about Hogsend Email gets a
|
|
6
|
+
// softer landing than Postmark does: a typo'd or unbuildable active provider is
|
|
7
|
+
// a config error, and the one thing it must never do is silently fall back to
|
|
8
|
+
// Resend and mail from the wrong sender.
|
|
9
|
+
//
|
|
10
|
+
// Env is set BEFORE the container is imported — env.ts validates at module
|
|
11
|
+
// scope. No DATABASE_URL connection is opened: `postgres()` is lazy and the
|
|
12
|
+
// throw happens during registry resolution, well before any query.
|
|
13
|
+
process.env.NODE_ENV ??= "test";
|
|
14
|
+
process.env.LOG_LEVEL ??= "error";
|
|
15
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
16
|
+
process.env.BETTER_AUTH_SECRET ??=
|
|
17
|
+
"test-secret-for-node-test-minimum-32-characters-long";
|
|
18
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
19
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
20
|
+
// The provider is SELECTED but nothing registers it: no HOGSEND_EMAIL_TOKEN
|
|
21
|
+
// (so the plugin is never even imported) and a Resend key so the registry is
|
|
22
|
+
// non-empty — which is the case that would otherwise silently degrade.
|
|
23
|
+
process.env.EMAIL_PROVIDER = "hogsend";
|
|
24
|
+
process.env.RESEND_API_KEY ??= "re_test_000000000000000000000000";
|
|
25
|
+
|
|
26
|
+
const { createHogsendClient } = await import("../container.js");
|
|
27
|
+
|
|
28
|
+
test("EMAIL_PROVIDER=hogsend with no provider registered throws at boot", () => {
|
|
29
|
+
assert.throws(
|
|
30
|
+
() => createHogsendClient(),
|
|
31
|
+
/email provider "hogsend" is not registered/,
|
|
32
|
+
);
|
|
33
|
+
});
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import type { env as envSchema } from "../env.js";
|
|
4
|
+
|
|
5
|
+
// A SEPARATE test file from email-providers-from-env.test.ts on purpose: that
|
|
6
|
+
// file's assertions require HOGSEND_EMAIL_TOKEN to be UNSET when the module's
|
|
7
|
+
// scope runs, while this one requires it SET. The node:test runner executes each
|
|
8
|
+
// file in its own process, so both postures hold simultaneously.
|
|
9
|
+
//
|
|
10
|
+
// The token must be in the environment BEFORE the module is imported — the
|
|
11
|
+
// guarded dynamic import of @hogsend/plugin-hogsend fires at module scope.
|
|
12
|
+
process.env.HOGSEND_EMAIL_TOKEN = "hsrel_preset_test_token";
|
|
13
|
+
|
|
14
|
+
// `lib/tracked.ts` (the home of the capability gate) validates the engine's env
|
|
15
|
+
// contract at module scope, so these must be in place before it is imported.
|
|
16
|
+
// Nothing here dials anything: the gate is a pure read of `provider.capabilities`.
|
|
17
|
+
process.env.NODE_ENV ??= "test";
|
|
18
|
+
process.env.LOG_LEVEL ??= "error";
|
|
19
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
20
|
+
process.env.BETTER_AUTH_SECRET ??=
|
|
21
|
+
"test-secret-for-node-test-minimum-32-characters-long";
|
|
22
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
23
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
24
|
+
|
|
25
|
+
const { providerConsumesIdempotencyKey } = await import("./tracked.js");
|
|
26
|
+
|
|
27
|
+
const RELAY = "https://cloud.example.com";
|
|
28
|
+
|
|
29
|
+
async function preset(over: Record<string, string | undefined> = {}) {
|
|
30
|
+
const { emailProvidersFromEnv } = await import(
|
|
31
|
+
"./email-providers-from-env.js"
|
|
32
|
+
);
|
|
33
|
+
return emailProvidersFromEnv({
|
|
34
|
+
HOGSEND_EMAIL_TOKEN: "hsrel_preset_test_token",
|
|
35
|
+
HOGSEND_EMAIL_RELAY_URL: RELAY,
|
|
36
|
+
HOGSEND_EMAIL_WEBHOOK_SECRET: "whsec_preset_test",
|
|
37
|
+
...over,
|
|
38
|
+
} as unknown as typeof envSchema);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
test("HOGSEND_EMAIL_TOKEN set → the env preset registers the `hogsend` provider", async () => {
|
|
42
|
+
const providers = await preset();
|
|
43
|
+
|
|
44
|
+
// @hogsend/plugin-hogsend is an engine optionalDependency, so the guarded
|
|
45
|
+
// dynamic import resolves and the preset produces a provider.
|
|
46
|
+
const hogsend = providers.find((p) => p.meta?.id === "hogsend");
|
|
47
|
+
assert.ok(hogsend, "expected a provider with meta.id === 'hogsend'");
|
|
48
|
+
assert.equal(typeof hogsend.send, "function");
|
|
49
|
+
// DECISIONS §3.6 — first-party tracking is sovereign, SES has no scheduled
|
|
50
|
+
// send, and the relay signs every webhook.
|
|
51
|
+
assert.equal(hogsend.capabilities?.nativeTracking, false);
|
|
52
|
+
assert.equal(hogsend.capabilities?.scheduledSend, false);
|
|
53
|
+
assert.equal(hogsend.capabilities?.signedWebhooks, true);
|
|
54
|
+
// The relay lifts `Idempotency-Key` off the message onto the relay REQUEST, so
|
|
55
|
+
// this transport is the one that may be handed the engine's internal key. It
|
|
56
|
+
// says so by DECLARING it — the engine no longer infers it from the id.
|
|
57
|
+
assert.equal(hogsend.capabilities?.consumesIdempotencyKey, true);
|
|
58
|
+
assert.equal(providerConsumesIdempotencyKey(hogsend), true);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
test("the REAL resend provider declares no such capability → wire unchanged", async () => {
|
|
62
|
+
// The non-breaking-change claim, asserted rather than assumed. Resend forwards
|
|
63
|
+
// `SendEmailOptions.headers` verbatim onto the delivered message, so if this
|
|
64
|
+
// ever flipped, every existing self-hosted deploy would start stamping Hatchet
|
|
65
|
+
// run ids — and, on campaign sends, the recipient's own address — onto real
|
|
66
|
+
// customer mail on nothing more than an engine upgrade.
|
|
67
|
+
const providers = await preset({ RESEND_API_KEY: "re_test_key" });
|
|
68
|
+
const resend = providers.find((p) => p.meta?.id === "resend");
|
|
69
|
+
|
|
70
|
+
assert.ok(resend, "expected a provider with meta.id === 'resend'");
|
|
71
|
+
assert.equal(resend.capabilities?.consumesIdempotencyKey, undefined);
|
|
72
|
+
assert.equal(providerConsumesIdempotencyKey(resend), false);
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
test("the preset REGISTERS the provider; it does not make it active", async () => {
|
|
76
|
+
// Postmark's exact posture: registering is not selecting. EMAIL_PROVIDER (or
|
|
77
|
+
// `email.defaultProvider`) is the only thing that switches the active wire, so
|
|
78
|
+
// a Cloud instance that somehow got a token without EMAIL_PROVIDER=hogsend
|
|
79
|
+
// keeps sending through whatever it sent through before.
|
|
80
|
+
const providers = await preset({ RESEND_API_KEY: "re_test_key" });
|
|
81
|
+
const ids = providers.map((p) => p.meta?.id);
|
|
82
|
+
assert.deepEqual(ids, ["resend", "hogsend"]);
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
test("token set but no relay URL → warns and skips, never a provider pointed at nowhere", async () => {
|
|
86
|
+
// The relay URL has NO default on purpose (staging and production control
|
|
87
|
+
// planes have different origins), so a token without one is a
|
|
88
|
+
// misconfiguration. Building the provider anyway would defer the failure to
|
|
89
|
+
// the first send, against an `undefined/api/email/send` URL. Silence would be
|
|
90
|
+
// worse still — the same swallowed-failure bug the Postmark block was fixed
|
|
91
|
+
// for — so it warns and names the missing variable.
|
|
92
|
+
const warnings: unknown[][] = [];
|
|
93
|
+
const original = console.warn;
|
|
94
|
+
console.warn = (...args: unknown[]) => {
|
|
95
|
+
warnings.push(args);
|
|
96
|
+
};
|
|
97
|
+
let providers: Awaited<ReturnType<typeof preset>>;
|
|
98
|
+
try {
|
|
99
|
+
providers = await preset({ HOGSEND_EMAIL_RELAY_URL: undefined });
|
|
100
|
+
} finally {
|
|
101
|
+
console.warn = original;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
assert.equal(
|
|
105
|
+
providers.find((p) => p.meta?.id === "hogsend"),
|
|
106
|
+
undefined,
|
|
107
|
+
);
|
|
108
|
+
assert.equal(warnings.length, 1);
|
|
109
|
+
assert.match(String(warnings[0]?.[0]), /HOGSEND_EMAIL_RELAY_URL/);
|
|
110
|
+
});
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import type { env as envSchema } from "../env.js";
|
|
4
|
+
import { emailProvidersFromEnv } from "./email-providers-from-env.js";
|
|
5
|
+
import { loadOptionalPlugin } from "./load-optional-plugin.js";
|
|
6
|
+
|
|
7
|
+
// This test process never sets HOGSEND_EMAIL_TOKEN (nor POSTMARK_SERVER_TOKEN),
|
|
8
|
+
// so the module-scope guarded dynamic imports in email-providers-from-env.ts
|
|
9
|
+
// must NOT have fired — which is exactly the posture the assertions below pin.
|
|
10
|
+
// The token-present posture lives in email-providers-from-env.hogsend.test.ts:
|
|
11
|
+
// node:test runs each file in its own process, so both hold simultaneously.
|
|
12
|
+
|
|
13
|
+
test("no HOGSEND_EMAIL_TOKEN → no hogsend provider (the package is never imported)", () => {
|
|
14
|
+
const providers = emailProvidersFromEnv({} as unknown as typeof envSchema);
|
|
15
|
+
assert.equal(
|
|
16
|
+
providers.find((p) => p.meta?.id === "hogsend"),
|
|
17
|
+
undefined,
|
|
18
|
+
);
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
test("token in the passed env but the factory never loaded → skipped, no throw", () => {
|
|
22
|
+
// HOGSEND_EMAIL_TOKEN was unset at module load, so the factory is null even
|
|
23
|
+
// when the *passed* env carries a token — the same degraded state as "token
|
|
24
|
+
// set but package not installed". The preset must skip, never throw: a
|
|
25
|
+
// container that then selects `hogsend` fails at boot with the registry's own
|
|
26
|
+
// unresolvable-provider error, which is the loud, correct place for it.
|
|
27
|
+
const providers = emailProvidersFromEnv({
|
|
28
|
+
HOGSEND_EMAIL_TOKEN: "hsrel_test_token",
|
|
29
|
+
HOGSEND_EMAIL_RELAY_URL: "https://cloud.example.com",
|
|
30
|
+
HOGSEND_EMAIL_WEBHOOK_SECRET: "whsec_test",
|
|
31
|
+
} as unknown as typeof envSchema);
|
|
32
|
+
assert.deepEqual(providers, []);
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
test("a hogsend load failure WARNS, naming the package and the enabling variable", async () => {
|
|
36
|
+
// The preset hands `loadOptionalPlugin` the same `enabledBy` string it uses
|
|
37
|
+
// in production. An INJECTED unresolvable specifier stands in for the real
|
|
38
|
+
// package: `@hogsend/plugin-hogsend` is an engine optionalDependency, so an
|
|
39
|
+
// absence-based test would silently invert its meaning once it resolves.
|
|
40
|
+
const warnings: string[] = [];
|
|
41
|
+
const factory = await loadOptionalPlugin({
|
|
42
|
+
specifier: "@hogsend/plugin-hogsend-does-not-exist",
|
|
43
|
+
exportName: "createHogsendEmailProvider",
|
|
44
|
+
enabledBy: "HOGSEND_EMAIL_TOKEN is set",
|
|
45
|
+
onFailure: (message) => warnings.push(message),
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
assert.equal(factory, null);
|
|
49
|
+
assert.equal(warnings.length, 1);
|
|
50
|
+
assert.match(warnings[0] ?? "", /@hogsend\/plugin-hogsend-does-not-exist/);
|
|
51
|
+
assert.match(warnings[0] ?? "", /HOGSEND_EMAIL_TOKEN is set/);
|
|
52
|
+
});
|