feat: carry email headers through the messaging types

.changeset/email-message-headers.md

@@ -0,0 +1,10 @@
+---
+"@seamless-auth/core": minor
+"@seamless-auth/express": minor
+"@seamless-auth/fastify": minor
+"@seamless-auth/nextjs": minor
+---
+
+`EmailMessage` carries an optional `headers` record, taken from `@seamless-auth/types` 0.34.0, so an override or a custom transport can send headers such as `List-Unsubscribe` and `List-Unsubscribe-Post`. Core passes an override's headers to the email transport untouched; `@seamless-auth/messaging-aws` sends them through SES v2 and validates the names and values.
+
+`SendEnrollmentInviteEmailInput` now comes from `@seamless-auth/types` rather than being declared in core, and the Express, Fastify and Next.js adapters export it alongside the other messaging types.

packages/core/src/authMessaging.ts

@@ -18,6 +18,7 @@ export type {
   DeliveryResult,
   EmailMessage,
   MessagingChannel,
+  SendEnrollmentInviteEmailInput,
   SendMagicLinkEmailInput,
   SendOtpEmailInput,
   SendOtpSmsInput,
@@ -30,19 +31,13 @@ import type {
   DeliveryPurpose,
   DeliveryResult,
   EmailMessage,
+  SendEnrollmentInviteEmailInput,
   SendMagicLinkEmailInput,
   SendOtpEmailInput,
   SendOtpSmsInput,
   SmsMessage,
 } from "@seamless-auth/types";
 
-export interface SendEnrollmentInviteEmailInput {
-  to: string;
-  signInUrl: string;
-  from?: string;
-  subject?: string;
-}
-
 /**
  * An owner notice the auth API asked this server to send, such as "account recovery
  * was requested". `text` is ready to send. `cancelUrl` carries a credential: send it

packages/core/tests/deliverAuthMessage.test.js

@@ -84,6 +84,30 @@ describe("deliverAuthMessage", () => {
     expect(email.send.mock.calls[0][0].subject).toBe("Code for user@acme.test");
   });
 
+  it("hands an override's headers to the transport untouched", async () => {
+    const email = emailTransport();
+    const headers = {
+      "List-Unsubscribe": "<https://acme.test/unsubscribe/abc>",
+      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+    };
+
+    await deliverAuthMessage(
+      {
+        email,
+        overrides: {
+          magicLinkEmail: (_input, defaults) => ({ ...defaults, headers }),
+        },
+      },
+      {
+        kind: "magic_link_email",
+        to: "user@acme.test",
+        magicLinkUrl: "https://acme.test/link",
+      },
+    );
+
+    expect(email.send.mock.calls[0][0].headers).toEqual(headers);
+  });
+
   it("routes an SMS instruction to the SMS transport", async () => {
     const sms = smsTransport();
 

packages/express/src/index.ts

@@ -26,6 +26,7 @@ export type {
   ResourceServerOptions,
   ResourceServerUser,
   SeamlessAuthMessagingOptions,
+  SendEnrollmentInviteEmailInput,
   StepUpRequirement,
   SeamlessUser,
   SmsMessage,

packages/express/tests/types/consumer.ts

@@ -6,6 +6,7 @@ import {
   getSeamlessUser,
   requireAuth,
   requireRole,
+  type EmailMessage,
 } from "@seamless-auth/express";
 
 const app = express();
@@ -33,3 +34,13 @@ requireRole(42);
 createSeamlessAuthServer(42);
 // @ts-expect-error getSeamlessUser takes a request and options
 getSeamlessUser(42);
+
+const unsubscribable: EmailMessage = {
+  to: "user@example.com",
+  subject: "News",
+  text: "Hello",
+  headers: { "List-Unsubscribe": "<https://example.com/unsubscribe>" },
+};
+// @ts-expect-error header values are strings
+const badHeader: EmailMessage = { ...unsubscribable, headers: { "X-Count": 1 } };
+void badHeader;

packages/fastify/src/index.ts

@@ -24,6 +24,7 @@ export type {
   ResourceServerOptions,
   ResourceServerUser,
   SeamlessAuthMessagingOptions,
+  SendEnrollmentInviteEmailInput,
   SeamlessAuthUser,
   SeamlessUser,
   SmsMessage,

packages/nextjs/src/index.ts

@@ -37,6 +37,7 @@ export type {
   ResourceServerOptions,
   ResourceServerUser,
   SeamlessAuthMessagingOptions,
+  SendEnrollmentInviteEmailInput,
   SeamlessAuthUser,
   SeamlessUser,
   SmsMessage,