@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.63.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": "^1.4.0",
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.63.0",
57
- "@hogsend/core": "^0.63.0",
58
- "@hogsend/db": "^0.63.0",
59
- "@hogsend/email": "^0.63.0",
60
- "@hogsend/plugin-posthog": "^0.63.0",
61
- "@hogsend/plugin-resend": "^0.63.0",
62
- "@hogsend/sms": "^0.63.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.63.0",
66
- "@hogsend/plugin-postmark": "^0.63.0",
67
- "@hogsend/plugin-twilio": "^0.63.0"
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
+ });
@@ -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
+ });