@hogsend/engine 0.63.0 → 0.65.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/account-links/__fixtures__/fake-fetch.test.ts +57 -0
- package/src/account-links/__fixtures__/fake-fetch.ts +114 -0
- package/src/account-links/__fixtures__/steam.json +21 -0
- package/src/account-links/__fixtures__/twitch.json +22 -0
- package/src/account-links/index.ts +8 -0
- package/src/account-links/steam.test.ts +243 -0
- package/src/account-links/steam.ts +48 -0
- package/src/account-links/twitch.test.ts +157 -0
- package/src/account-links/twitch.ts +99 -0
- package/src/container.account-links.env.test.ts +65 -0
- package/src/container.account-links.halfenv.test.ts +48 -0
- package/src/container.account-links.test.ts +185 -0
- package/src/container.ts +120 -0
- package/src/env.ts +60 -0
- package/src/index.ts +104 -1
- package/src/journeys/journey-boundary.ts +8 -0
- package/src/lib/account-link-emit.ts +126 -0
- package/src/lib/account-link-events.ts +180 -0
- package/src/lib/account-link-hooks.test.ts +158 -0
- package/src/lib/account-link-hooks.ts +73 -0
- package/src/lib/account-link-ingest.ts +364 -0
- package/src/lib/account-link-nonce.test.ts +52 -0
- package/src/lib/account-link-nonce.ts +57 -0
- package/src/lib/account-link-origins.test.ts +72 -0
- package/src/lib/account-link-origins.ts +87 -0
- package/src/lib/account-link-pkce.test.ts +91 -0
- package/src/lib/account-link-pkce.ts +106 -0
- package/src/lib/account-link-provider-registry.test.ts +52 -0
- package/src/lib/account-link-provider-registry.ts +61 -0
- package/src/lib/account-link-throttle.test.ts +178 -0
- package/src/lib/account-link-throttle.ts +130 -0
- package/src/lib/account-link-url.ts +85 -0
- package/src/lib/account-links-emit.test.ts +525 -0
- package/src/lib/account-links-env.test.ts +40 -0
- package/src/lib/account-links-from-env.test.ts +187 -0
- package/src/lib/account-links-from-env.ts +126 -0
- package/src/lib/account-links.ts +1300 -0
- package/src/lib/app-secret.ts +34 -0
- package/src/lib/attachments.ts +81 -0
- package/src/lib/connector-actions.test.ts +13 -4
- package/src/lib/connector-state.account-link.test.ts +114 -0
- package/src/lib/connector-state.ts +48 -3
- package/src/lib/contacts.ts +320 -6
- 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-account-payloads.test.ts +137 -0
- package/src/lib/outbound.ts +126 -0
- package/src/lib/provider-credentials.ts +19 -5
- 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-catalog-sync.test.ts +24 -0
- package/src/lib/webhook-signing.ts +25 -1
- package/src/routes/accounts/callback.ts +597 -0
- package/src/routes/accounts/emit.ts +231 -0
- package/src/routes/accounts/import-links.ts +210 -0
- package/src/routes/accounts/index.ts +75 -0
- package/src/routes/accounts/lookup.ts +177 -0
- package/src/routes/accounts/me.ts +215 -0
- package/src/routes/accounts/mint.ts +279 -0
- package/src/routes/accounts/pages.ts +62 -0
- package/src/routes/accounts/resolve.ts +61 -0
- package/src/routes/accounts/serialize.ts +96 -0
- package/src/routes/accounts/shared.ts +107 -0
- package/src/routes/accounts/start.ts +229 -0
- package/src/routes/accounts/unlink.ts +98 -0
- package/src/routes/admin/agent.ts +2 -0
- package/src/routes/admin/api-keys.ts +7 -0
- package/src/routes/admin/contacts.ts +38 -2
- 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/src/routes/connectors/index.ts +17 -0
- package/src/routes/contacts/index.ts +8 -0
- package/src/routes/index.ts +75 -0
- package/src/testing-barrel.test.ts +74 -0
- package/src/testing.ts +17 -0
|
@@ -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
|
+
});
|
|
@@ -46,6 +46,38 @@ if (process.env.POSTMARK_SERVER_TOKEN) {
|
|
|
46
46
|
});
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
+
/**
|
|
50
|
+
* `@hogsend/plugin-hogsend` is OPT-IN for exactly the same reasons as Postmark,
|
|
51
|
+
* and loaded exactly the same way: an engine `optionalDependency` behind a
|
|
52
|
+
* top-level guarded dynamic import whose specifier is ASSEMBLED AT RUNTIME. A
|
|
53
|
+
* string literal here would make `tsc` resolve the module's types and fail with
|
|
54
|
+
* TS2307 for every consumer that doesn't have the package installed — including
|
|
55
|
+
* every fresh `create-hogsend` app, which is not covered by this repo's own
|
|
56
|
+
* type-check and so would only surface after publish.
|
|
57
|
+
*
|
|
58
|
+
* The gate is `HOGSEND_EMAIL_TOKEN`: absent, the `import()` never fires, so a
|
|
59
|
+
* self-hosted deploy that will never send through Hogsend Cloud never touches
|
|
60
|
+
* the package.
|
|
61
|
+
*/
|
|
62
|
+
type CreateHogsendEmailProvider = (cfg: {
|
|
63
|
+
relayUrl: string;
|
|
64
|
+
tenantToken: string;
|
|
65
|
+
webhookSecret?: string;
|
|
66
|
+
}) => EmailProvider;
|
|
67
|
+
|
|
68
|
+
const HOGSEND_PACKAGE = ["@hogsend", "plugin-hogsend"].join("/");
|
|
69
|
+
|
|
70
|
+
let createHogsendEmailProvider: CreateHogsendEmailProvider | null = null;
|
|
71
|
+
if (process.env.HOGSEND_EMAIL_TOKEN) {
|
|
72
|
+
createHogsendEmailProvider =
|
|
73
|
+
await loadOptionalPlugin<CreateHogsendEmailProvider>({
|
|
74
|
+
specifier: HOGSEND_PACKAGE,
|
|
75
|
+
exportName: "createHogsendEmailProvider",
|
|
76
|
+
enabledBy: "HOGSEND_EMAIL_TOKEN is set",
|
|
77
|
+
onFailure: (message) => console.warn(message),
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
|
|
49
81
|
/**
|
|
50
82
|
* Build the env-enabled email-provider presets. Mirrors `destinationsFromEnv`:
|
|
51
83
|
* a preset is constructed ONLY when its credential is present, so a
|
|
@@ -94,5 +126,40 @@ export function emailProvidersFromEnv(env: typeof envSchema): EmailProvider[] {
|
|
|
94
126
|
);
|
|
95
127
|
}
|
|
96
128
|
|
|
129
|
+
// Hogsend Email is OPT-IN twice over: the package only loads when
|
|
130
|
+
// HOGSEND_EMAIL_TOKEN is set (see the guarded import above), and registering
|
|
131
|
+
// it does NOT select it — EMAIL_PROVIDER=hogsend does, exactly as Postmark
|
|
132
|
+
// works. The Cloud provisioner injects both, so a Cloud instance gets it by
|
|
133
|
+
// default while every self-hosted default is untouched.
|
|
134
|
+
//
|
|
135
|
+
// The relay URL is required to BUILD it. A token with no URL is a
|
|
136
|
+
// misconfiguration, and a provider aimed at `undefined/api/email/send` would
|
|
137
|
+
// defer that config error to the first real send — so it warns here and skips.
|
|
138
|
+
// If `hogsend` was the selected provider the container then throws its own
|
|
139
|
+
// "not registered" error at boot, and the two lines together say exactly what
|
|
140
|
+
// is missing.
|
|
141
|
+
if (env.HOGSEND_EMAIL_TOKEN && createHogsendEmailProvider) {
|
|
142
|
+
if (!env.HOGSEND_EMAIL_RELAY_URL) {
|
|
143
|
+
console.warn(
|
|
144
|
+
"HOGSEND_EMAIL_TOKEN is set, but its env preset is skipped: " +
|
|
145
|
+
"HOGSEND_EMAIL_RELAY_URL is unset, so there is no Hogsend Cloud " +
|
|
146
|
+
"control plane to relay sends to. Set it to your control plane " +
|
|
147
|
+
"origin (Cloud provisioning injects it automatically).",
|
|
148
|
+
);
|
|
149
|
+
} else {
|
|
150
|
+
providers.push(
|
|
151
|
+
createHogsendEmailProvider({
|
|
152
|
+
relayUrl: env.HOGSEND_EMAIL_RELAY_URL,
|
|
153
|
+
tenantToken: env.HOGSEND_EMAIL_TOKEN,
|
|
154
|
+
// Absent ⇒ the provider fails closed on every inbound webhook. Sends
|
|
155
|
+
// still work; only status updates stop.
|
|
156
|
+
...(env.HOGSEND_EMAIL_WEBHOOK_SECRET
|
|
157
|
+
? { webhookSecret: env.HOGSEND_EMAIL_WEBHOOK_SECRET }
|
|
158
|
+
: {}),
|
|
159
|
+
}),
|
|
160
|
+
);
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
97
164
|
return providers;
|
|
98
165
|
}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type {
|
|
2
2
|
BatchEmailItem,
|
|
3
3
|
DurationObject,
|
|
4
|
+
EmailAttachment,
|
|
4
5
|
EmailEvent,
|
|
5
6
|
EmailEventType,
|
|
6
7
|
SendEmailOptions,
|
|
@@ -66,6 +67,14 @@ export interface SendTrackedEmailOptions<
|
|
|
66
67
|
* duplicate provider send.
|
|
67
68
|
*/
|
|
68
69
|
idempotencyKey?: string;
|
|
70
|
+
/**
|
|
71
|
+
* Neutral attachments (PRD 17), validated + capability-gated before ANY send
|
|
72
|
+
* work (see `assertAttachmentsSendable`) and handed to the provider alongside
|
|
73
|
+
* the TRACKED html — tracking is applied first, attachments ride alongside;
|
|
74
|
+
* an attachment never causes tracking to be skipped. `email_sends.metadata`
|
|
75
|
+
* records filenames/sizes/types only, never the bytes.
|
|
76
|
+
*/
|
|
77
|
+
attachments?: EmailAttachment[];
|
|
69
78
|
}
|
|
70
79
|
|
|
71
80
|
export interface TrackedSendResult {
|
|
@@ -184,6 +193,8 @@ export interface EmailServiceSendOptions<
|
|
|
184
193
|
skipPreferenceCheck?: boolean;
|
|
185
194
|
/** Caller-supplied idempotency key (POST /v1/emails) — dedups duplicate sends. */
|
|
186
195
|
idempotencyKey?: string;
|
|
196
|
+
/** Neutral attachments — see `SendTrackedEmailOptions.attachments`. */
|
|
197
|
+
attachments?: EmailAttachment[];
|
|
187
198
|
}
|
|
188
199
|
|
|
189
200
|
/**
|
package/src/lib/email.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { EmailAttachment } from "@hogsend/core";
|
|
1
2
|
import { generateUnsubscribeUrl, type TemplateName } from "@hogsend/email";
|
|
2
3
|
import {
|
|
3
4
|
deriveJourneyKey,
|
|
@@ -65,6 +66,18 @@ export interface SendEmailOptions {
|
|
|
65
66
|
* engine throws an intra-run key-collision error. Additive and optional.
|
|
66
67
|
*/
|
|
67
68
|
idempotencyLabel?: string;
|
|
69
|
+
/**
|
|
70
|
+
* Files to send with the email (invoices, receipts, tickets, exports).
|
|
71
|
+
* Neutral {@link EmailAttachment} shape; validated + capability-gated by the
|
|
72
|
+
* tracked mailer BEFORE any work — a provider that does not declare
|
|
73
|
+
* `capabilities.attachments` throws rather than delivering the message
|
|
74
|
+
* without its files. Attachments do NOT enter the replay-stable idempotency
|
|
75
|
+
* key (that stays `kind:anchor:site:template`), so no authoring change is
|
|
76
|
+
* needed for exactly-once — but if something NON-deterministic picks the
|
|
77
|
+
* attachment, wrap that choice in `ctx.once` like any other non-deterministic
|
|
78
|
+
* send input.
|
|
79
|
+
*/
|
|
80
|
+
attachments?: EmailAttachment[];
|
|
68
81
|
}
|
|
69
82
|
|
|
70
83
|
export interface SendEmailResult {
|
|
@@ -154,6 +167,7 @@ export async function sendEmail(
|
|
|
154
167
|
{ name: "userId", value: opts.userId },
|
|
155
168
|
],
|
|
156
169
|
headers,
|
|
170
|
+
attachments: opts.attachments,
|
|
157
171
|
} as unknown as EmailServiceSendOptions;
|
|
158
172
|
|
|
159
173
|
const effect = {
|
|
@@ -172,6 +186,9 @@ export async function sendEmail(
|
|
|
172
186
|
...(resolvedIdempotencyKey
|
|
173
187
|
? { idempotencyKey: resolvedIdempotencyKey }
|
|
174
188
|
: {}),
|
|
189
|
+
// Carried on the effect so a scoped services.email override (deterministic
|
|
190
|
+
// journey harnesses) sees the files too, instead of silently dropping them.
|
|
191
|
+
...(opts.attachments?.length ? { attachments: opts.attachments } : {}),
|
|
175
192
|
};
|
|
176
193
|
|
|
177
194
|
// Layer 1 (fast path): when inside a journey on an eviction-capable engine,
|