@hogsend/plugin-resend 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/plugin-resend",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -24,8 +24,8 @@
   "dependencies": {
     "resend": "^6.12.3",
     "svix": "^1.94.0",
-    "@hogsend/core": "^0.11.0",
-    "@hogsend/email": "^0.11.0"
+    "@hogsend/core": "^0.12.1",
+    "@hogsend/email": "^0.12.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/__tests__/domains.test.ts

@@ -0,0 +1,255 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createResendDomains } from "../domains.js";
+
+/**
+ * Mocked-fetch fixtures for the Resend Domains REST API. NEVER hits the real
+ * service — every test stubs `globalThis.fetch`.
+ */
+
+const DOMAIN_ID = "d91cd9bd-1176-453e-8fc1-35364d380206";
+
+const DOMAIN_DETAIL = {
+  object: "domain",
+  id: DOMAIN_ID,
+  name: "mysite.com",
+  status: "not_started",
+  created_at: "2026-06-09T00:00:00.000Z",
+  region: "us-east-1",
+  records: [
+    {
+      record: "SPF",
+      name: "send",
+      type: "MX",
+      ttl: "Auto",
+      status: "not_started",
+      value: "feedback-smtp.us-east-1.amazonses.com",
+      priority: 10,
+    },
+    {
+      record: "SPF",
+      name: "send",
+      type: "TXT",
+      ttl: "Auto",
+      status: "pending",
+      value: "v=spf1 include:amazonses.com ~all",
+    },
+    {
+      record: "DKIM",
+      name: "resend._domainkey",
+      type: "TXT",
+      ttl: "Auto",
+      status: "verified",
+      value: "p=MIGfMA0GCSqGSIb3...",
+    },
+    {
+      record: "DKIM",
+      name: "broken._domainkey",
+      type: "TXT",
+      ttl: "Auto",
+      status: "failure",
+      value: "p=BROKEN",
+    },
+  ],
+};
+
+const DOMAIN_LIST = {
+  data: [
+    { id: DOMAIN_ID, name: "mysite.com", status: "not_started" },
+    { id: "other-id", name: "other.com", status: "verified" },
+  ],
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  fetchMock.mockReset();
+  vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+const domains = createResendDomains({ apiKey: "re_test_key" });
+
+describe("createResendDomains — create", () => {
+  it("POSTs /domains with the bearer token and normalizes the response", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(DOMAIN_DETAIL, 201));
+
+    const status = await domains.create("mysite.com");
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://api.resend.com/domains");
+    expect(init.method).toBe("POST");
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      "Bearer re_test_key",
+    );
+    expect(JSON.parse(init.body as string)).toEqual({ name: "mysite.com" });
+
+    expect(status.domain).toBe("mysite.com");
+    expect(status.providerId).toBe("resend");
+    expect(status.state).toBe("pending"); // not_started → pending
+    expect(status.raw).toEqual(DOMAIN_DETAIL);
+    expect(typeof status.checkedAt).toBe("string");
+  });
+
+  it("falls through to lookup when the domain already exists (idempotent)", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse(
+          {
+            statusCode: 409,
+            name: "conflict",
+            message: "Domain already exists",
+          },
+          409,
+        ),
+      )
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_DETAIL));
+
+    const status = await domains.create("mysite.com");
+    expect(status.domain).toBe("mysite.com");
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  it("throws on other API errors", async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ statusCode: 401, message: "API key is invalid" }, 401),
+    );
+    await expect(domains.create("mysite.com")).rejects.toThrow(
+      /API key is invalid/,
+    );
+  });
+});
+
+describe("createResendDomains — get", () => {
+  it("resolves name → id via the list, then normalizes the detail", async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_DETAIL));
+
+    const status = await domains.get("mysite.com");
+    expect(status).not.toBeNull();
+    expect(status?.domain).toBe("mysite.com");
+
+    // The detail GET hit /domains/:id.
+    const [detailUrl] = fetchMock.mock.calls[1] as [string];
+    expect(detailUrl).toBe(`https://api.resend.com/domains/${DOMAIN_ID}`);
+  });
+
+  it("returns null when the provider doesn't know the domain", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(DOMAIN_LIST));
+    const status = await domains.get("unknown.com");
+    expect(status).toBeNull();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("normalizes records: purpose + status mapping table", async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_DETAIL));
+
+    const status = await domains.get("mysite.com");
+    const records = status?.records ?? [];
+    expect(records).toHaveLength(4);
+
+    // SPF + MX type → purpose spf (record kind wins), priority preserved.
+    expect(records[0]).toMatchObject({
+      type: "MX",
+      name: "send",
+      purpose: "spf",
+      priority: 10,
+      status: "pending", // not_started → pending
+    });
+    // SPF TXT.
+    expect(records[1]).toMatchObject({
+      type: "TXT",
+      purpose: "spf",
+      status: "pending",
+    });
+    // DKIM verified.
+    expect(records[2]).toMatchObject({
+      name: "resend._domainkey",
+      purpose: "dkim",
+      status: "verified",
+    });
+    // DKIM failure → failed.
+    expect(records[3]).toMatchObject({ purpose: "dkim", status: "failed" });
+  });
+
+  it("maps domain status → DomainVerificationState", async () => {
+    for (const [provider, expected] of [
+      ["verified", "verified"],
+      ["failure", "failed"],
+      ["pending", "pending"],
+      ["temporary_failure", "pending"],
+      ["not_started", "pending"],
+    ] as const) {
+      fetchMock.mockReset();
+      fetchMock
+        .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+        .mockResolvedValueOnce(
+          jsonResponse({ ...DOMAIN_DETAIL, status: provider }),
+        );
+      const status = await domains.get("mysite.com");
+      expect(status?.state).toBe(expected);
+    }
+  });
+});
+
+describe("createResendDomains — records", () => {
+  it("returns the normalized record list", async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_DETAIL));
+    const records = await domains.records("mysite.com");
+    expect(records).toHaveLength(4);
+  });
+
+  it("returns [] for an unknown domain", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(DOMAIN_LIST));
+    const records = await domains.records("unknown.com");
+    expect(records).toEqual([]);
+  });
+});
+
+describe("createResendDomains — verify", () => {
+  it("POSTs /domains/:id/verify then re-fetches the status", async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+      .mockResolvedValueOnce(jsonResponse({ object: "domain", id: DOMAIN_ID }))
+      .mockResolvedValueOnce(
+        jsonResponse({ ...DOMAIN_DETAIL, status: "verified" }),
+      );
+
+    // biome-ignore lint/style/noNonNullAssertion: verify is implemented for Resend
+    const status = await domains.verify!("mysite.com");
+
+    const [verifyUrl, verifyInit] = fetchMock.mock.calls[1] as [
+      string,
+      RequestInit,
+    ];
+    expect(verifyUrl).toBe(
+      `https://api.resend.com/domains/${DOMAIN_ID}/verify`,
+    );
+    expect(verifyInit.method).toBe("POST");
+    expect(status.state).toBe("verified");
+  });
+
+  it("throws when the domain is unknown", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(DOMAIN_LIST));
+    // biome-ignore lint/style/noNonNullAssertion: verify is implemented for Resend
+    await expect(domains.verify!("unknown.com")).rejects.toThrow(
+      /not registered/,
+    );
+  });
+});

package/src/domains.ts

@@ -0,0 +1,194 @@
+import type {
+  DnsRecord,
+  DnsRecordPurpose,
+  DnsRecordStatus,
+  DomainStatus,
+  DomainsCapability,
+  DomainVerificationState,
+} from "@hogsend/core";
+
+/**
+ * The Resend implementation of the {@link DomainsCapability} contract — a dumb
+ * wire over the Resend Domains REST API (`https://api.resend.com/domains`).
+ * Plain `fetch` with the bearer token; all caching/policy lives in the engine's
+ * `DomainStatusService`, never here.
+ */
+export interface ResendDomainsConfig {
+  apiKey: string;
+}
+
+const BASE_URL = "https://api.resend.com";
+
+/** Resend's per-record verification statuses → neutral {@link DnsRecordStatus}. */
+const RECORD_STATUS: Record<string, DnsRecordStatus> = {
+  verified: "verified",
+  failure: "failed",
+  not_started: "pending",
+  pending: "pending",
+  temporary_failure: "pending",
+};
+
+/** Resend's domain statuses → neutral {@link DomainVerificationState}. */
+const DOMAIN_STATE: Record<string, DomainVerificationState> = {
+  verified: "verified",
+  failure: "failed",
+  not_started: "pending",
+  pending: "pending",
+  temporary_failure: "pending",
+};
+
+/** A record as Resend's `GET /domains/:id` reports it. */
+interface ResendRecord {
+  record?: string; // "SPF" | "DKIM"
+  type?: string; // "TXT" | "CNAME" | "MX"
+  name?: string;
+  value?: string;
+  ttl?: string | number;
+  priority?: number;
+  status?: string;
+}
+
+interface ResendDomainPayload {
+  id?: string;
+  name?: string;
+  status?: string;
+  records?: ResendRecord[];
+}
+
+function recordPurpose(r: ResendRecord): DnsRecordPurpose {
+  const kind = (r.record ?? "").toUpperCase();
+  if (kind === "SPF") return "spf";
+  if (kind === "DKIM") return "dkim";
+  if ((r.type ?? "").toUpperCase() === "MX") return "mx";
+  return "other";
+}
+
+function toDnsRecord(r: ResendRecord): DnsRecord {
+  const type = (r.type ?? "TXT").toUpperCase();
+  return {
+    type: type === "CNAME" ? "CNAME" : type === "MX" ? "MX" : "TXT",
+    name: r.name ?? "",
+    value: r.value ?? "",
+    ...(typeof r.ttl === "number" ? { ttl: r.ttl } : {}),
+    ...(typeof r.priority === "number" ? { priority: r.priority } : {}),
+    purpose: recordPurpose(r),
+    status: RECORD_STATUS[r.status ?? ""] ?? "unknown",
+  };
+}
+
+function toDomainStatus(payload: ResendDomainPayload): DomainStatus {
+  return {
+    domain: payload.name ?? "",
+    state: DOMAIN_STATE[payload.status ?? ""] ?? "pending",
+    records: (payload.records ?? []).map(toDnsRecord),
+    providerId: "resend",
+    checkedAt: new Date().toISOString(),
+    raw: payload,
+  };
+}
+
+function errorMessage(status: number, body: unknown): string {
+  if (
+    body &&
+    typeof body === "object" &&
+    "message" in body &&
+    typeof (body as { message: unknown }).message === "string"
+  ) {
+    return `Resend domains API ${status}: ${(body as { message: string }).message}`;
+  }
+  return `Resend domains API request failed with status ${status}`;
+}
+
+/** Build the Resend {@link DomainsCapability}. */
+export function createResendDomains(
+  config: ResendDomainsConfig,
+): DomainsCapability {
+  const api = async (
+    path: string,
+    init?: { method?: string; body?: unknown },
+  ): Promise<{ ok: boolean; status: number; body: unknown }> => {
+    const res = await fetch(`${BASE_URL}${path}`, {
+      method: init?.method ?? "GET",
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        ...(init?.body !== undefined
+          ? { "Content-Type": "application/json" }
+          : {}),
+      },
+      body: init?.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      body = undefined;
+    }
+    return { ok: res.ok, status: res.status, body };
+  };
+
+  /** Resolve a domain name → Resend domain id via `GET /domains`. */
+  const findId = async (domain: string): Promise<string | null> => {
+    const res = await api("/domains");
+    if (!res.ok) throw new Error(errorMessage(res.status, res.body));
+    const data =
+      res.body && typeof res.body === "object" && "data" in res.body
+        ? (res.body as { data: ResendDomainPayload[] }).data
+        : [];
+    const match = (data ?? []).find((d) => d.name === domain);
+    return match?.id ?? null;
+  };
+
+  /** Fetch + normalize `GET /domains/:id`. */
+  const getById = async (id: string): Promise<DomainStatus> => {
+    const res = await api(`/domains/${id}`);
+    if (!res.ok) throw new Error(errorMessage(res.status, res.body));
+    return toDomainStatus(res.body as ResendDomainPayload);
+  };
+
+  const get = async (domain: string): Promise<DomainStatus | null> => {
+    const id = await findId(domain);
+    if (id === null) return null;
+    return getById(id);
+  };
+
+  return {
+    async create(domain: string): Promise<DomainStatus> {
+      const res = await api("/domains", {
+        method: "POST",
+        body: { name: domain },
+      });
+      if (res.ok) return toDomainStatus(res.body as ResendDomainPayload);
+
+      // Idempotent create: an "already exists" conflict falls through to lookup.
+      const message =
+        res.body && typeof res.body === "object" && "message" in res.body
+          ? String((res.body as { message: unknown }).message)
+          : "";
+      if (res.status === 409 || /already exists/i.test(message)) {
+        const existing = await get(domain);
+        if (existing) return existing;
+      }
+      throw new Error(errorMessage(res.status, res.body));
+    },
+
+    get,
+
+    async records(domain: string): Promise<DnsRecord[]> {
+      const status = await get(domain);
+      return status?.records ?? [];
+    },
+
+    async verify(domain: string): Promise<DomainStatus> {
+      const id = await findId(domain);
+      if (id === null) {
+        throw new Error(
+          `domain "${domain}" is not registered with Resend — run create first`,
+        );
+      }
+      const res = await api(`/domains/${id}/verify`, { method: "POST" });
+      if (!res.ok) throw new Error(errorMessage(res.status, res.body));
+      // The verify response carries no records — re-fetch the fresh status.
+      return getById(id);
+    },
+  };
+}

package/src/index.ts

@@ -1,5 +1,10 @@
 // Client
 export { createResendClient } from "./client.js";
+// Sending-domain capability (Resend Domains REST API)
+export {
+  createResendDomains,
+  type ResendDomainsConfig,
+} from "./domains.js";
 // EmailProvider (the provider contract + Resend implementation)
 export {
   createResendProvider,

package/src/provider.ts

@@ -1,5 +1,6 @@
 import type { RetryOptions } from "@hogsend/email";
 import { createResendClient } from "./client.js";
+import { createResendDomains } from "./domains.js";
 import { sendBatchEmails, sendEmail } from "./send.js";
 import {
   type BatchEmailItem,
@@ -39,6 +40,10 @@ export function createResendProvider(
       signedWebhooks: true,
     },
 
+    // Sending-domain management (Resend Domains REST API). Presence of this
+    // member is the engine's capability gate for /v1/admin/domain.
+    domains: createResendDomains({ apiKey: config.apiKey }),
+
     async send(options: SendEmailOptions): Promise<SendResult> {
       return sendEmail({ client, options, retryOptions });
     },