@hogsend/plugin-postmark 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/plugin-postmark",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "postmark": "^4.0.7",
-    "@hogsend/core": "^0.11.0"
+    "@hogsend/core": "^0.12.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/__tests__/domains.test.ts

@@ -0,0 +1,267 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * Mocked-fetch fixtures for Postmark's account-token Domains API. NEVER hits
+ * the real service — every test stubs `globalThis.fetch`. The send wire's
+ * ServerClient is mocked too so `createPostmarkProvider` never opens a socket.
+ */
+
+vi.mock("postmark", async () => {
+  const actual = await vi.importActual<typeof import("postmark")>("postmark");
+  class MockServerClient {
+    sendEmail = vi.fn();
+    sendEmailBatch = vi.fn();
+  }
+  return { ...actual, ServerClient: MockServerClient };
+});
+
+const { createPostmarkProvider } = await import("../index.js");
+
+const DOMAIN_ID = 1234;
+
+const DOMAIN_DETAIL = {
+  ID: DOMAIN_ID,
+  Name: "mysite.com",
+  SPFVerified: true,
+  DKIMVerified: false,
+  WeakDKIM: false,
+  DKIMHost: "",
+  DKIMTextValue: "",
+  DKIMPendingHost: "20260609._domainkey.mysite.com",
+  DKIMPendingTextValue: "k=rsa; p=MIGfMA0GCSq...",
+  DKIMRevokedHost: "",
+  DKIMRevokedTextValue: "",
+  SafeToRemoveRevokedKeyFromDNS: false,
+  DKIMUpdateStatus: "Pending",
+  ReturnPathDomain: "pm-bounces.mysite.com",
+  ReturnPathDomainVerified: false,
+  ReturnPathDomainCNAMEValue: "pm.mtasv.net",
+};
+
+const DOMAIN_LIST = {
+  TotalCount: 2,
+  Domains: [
+    { ID: DOMAIN_ID, Name: "mysite.com" },
+    { ID: 99, Name: "other.com" },
+  ],
+};
+
+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();
+});
+
+describe("capability gate", () => {
+  it("omits `domains` entirely when accountToken is absent", () => {
+    const provider = createPostmarkProvider({ serverToken: "pm_server" });
+    expect(provider.domains).toBeUndefined();
+  });
+
+  it("exposes `domains` when accountToken is configured", () => {
+    const provider = createPostmarkProvider({
+      serverToken: "pm_server",
+      accountToken: "pm_account",
+    });
+    expect(provider.domains).toBeDefined();
+  });
+});
+
+const provider = createPostmarkProvider({
+  serverToken: "pm_server",
+  accountToken: "pm_account",
+});
+// biome-ignore lint/style/noNonNullAssertion: accountToken is set above
+const domains = provider.domains!;
+
+function assertAccountTokenHeader(): void {
+  for (const call of fetchMock.mock.calls) {
+    const init = call[1] as RequestInit;
+    const headers = init.headers as Record<string, string>;
+    expect(headers["X-Postmark-Account-Token"]).toBe("pm_account");
+  }
+}
+
+describe("createPostmarkProvider(...).domains — get", () => {
+  it("resolves name → ID via the list, synthesizes DKIM + return-path records", 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");
+    expect(status?.providerId).toBe("postmark");
+    expect(status?.raw).toEqual(DOMAIN_DETAIL);
+
+    const [listUrl] = fetchMock.mock.calls[0] as [string];
+    expect(listUrl).toContain("https://api.postmarkapp.com/domains?count=");
+    const [detailUrl] = fetchMock.mock.calls[1] as [string];
+    expect(detailUrl).toBe(`https://api.postmarkapp.com/domains/${DOMAIN_ID}`);
+    assertAccountTokenHeader();
+
+    // DKIM record synthesized from the PENDING host/value (rotation pending).
+    const dkim = status?.records.find((r) => r.purpose === "dkim");
+    expect(dkim).toMatchObject({
+      type: "TXT",
+      name: "20260609._domainkey.mysite.com",
+      value: "k=rsa; p=MIGfMA0GCSq...",
+      status: "pending",
+    });
+
+    // Return-path CNAME.
+    const rp = status?.records.find((r) => r.purpose === "return_path");
+    expect(rp).toMatchObject({
+      type: "CNAME",
+      name: "pm-bounces.mysite.com",
+      value: "pm.mtasv.net",
+      status: "pending",
+    });
+  });
+
+  it("uses the active DKIM host/value when no rotation is pending", async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...DOMAIN_DETAIL,
+          DKIMVerified: true,
+          DKIMHost: "pm._domainkey.mysite.com",
+          DKIMTextValue: "k=rsa; p=ACTIVE",
+          DKIMPendingHost: "",
+          DKIMPendingTextValue: "",
+        }),
+      );
+
+    const status = await domains.get("mysite.com");
+    const dkim = status?.records.find((r) => r.purpose === "dkim");
+    expect(dkim).toMatchObject({
+      name: "pm._domainkey.mysite.com",
+      value: "k=rsa; p=ACTIVE",
+      status: "verified",
+    });
+  });
+
+  it("state is verified ONLY when both DKIM and return-path are verified", async () => {
+    for (const [dkimV, rpV, expected] of [
+      [true, true, "verified"],
+      [true, false, "pending"],
+      [false, true, "pending"],
+      [false, false, "pending"],
+    ] as const) {
+      fetchMock.mockReset();
+      fetchMock
+        .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+        .mockResolvedValueOnce(
+          jsonResponse({
+            ...DOMAIN_DETAIL,
+            DKIMVerified: dkimV,
+            ReturnPathDomainVerified: rpV,
+          }),
+        );
+      const status = await domains.get("mysite.com");
+      expect(status?.state).toBe(expected);
+    }
+  });
+
+  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();
+  });
+});
+
+describe("createPostmarkProvider(...).domains — create", () => {
+  it("POSTs /domains with the account token and normalizes", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(DOMAIN_DETAIL));
+
+    const status = await domains.create("mysite.com");
+
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://api.postmarkapp.com/domains");
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({ Name: "mysite.com" });
+    assertAccountTokenHeader();
+    expect(status.domain).toBe("mysite.com");
+    expect(status.state).toBe("pending");
+  });
+
+  it("falls through to lookup on 422 already-exists (idempotent)", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse(
+          { ErrorCode: 503, Message: "This domain already exists." },
+          422,
+        ),
+      )
+      .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({ ErrorCode: 10, Message: "Bad account token" }, 401),
+    );
+    await expect(domains.create("mysite.com")).rejects.toThrow(
+      /Bad account token/,
+    );
+  });
+});
+
+describe("createPostmarkProvider(...).domains — verify", () => {
+  it("runs verifyDkim + verifyReturnPath, then re-gets", async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(DOMAIN_LIST))
+      .mockResolvedValueOnce(jsonResponse({ ...DOMAIN_DETAIL }))
+      .mockResolvedValueOnce(jsonResponse({ ...DOMAIN_DETAIL }))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...DOMAIN_DETAIL,
+          DKIMVerified: true,
+          ReturnPathDomainVerified: true,
+        }),
+      );
+
+    // biome-ignore lint/style/noNonNullAssertion: verify is implemented for Postmark
+    const status = await domains.verify!("mysite.com");
+
+    const calls = fetchMock.mock.calls.map((c) => [
+      (c[1] as RequestInit).method ?? "GET",
+      c[0] as string,
+    ]);
+    expect(calls).toEqual([
+      ["GET", expect.stringContaining("/domains?count=")],
+      ["PUT", `https://api.postmarkapp.com/domains/${DOMAIN_ID}/verifyDkim`],
+      [
+        "PUT",
+        `https://api.postmarkapp.com/domains/${DOMAIN_ID}/verifyReturnPath`,
+      ],
+      ["GET", `https://api.postmarkapp.com/domains/${DOMAIN_ID}`],
+    ]);
+    expect(status.state).toBe("verified");
+  });
+});
+
+describe("createPostmarkProvider(...).domains — records", () => {
+  it("returns [] for an unknown domain", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(DOMAIN_LIST));
+    const records = await domains.records("unknown.com");
+    expect(records).toEqual([]);
+  });
+});

package/src/index.ts

@@ -1,6 +1,9 @@
 import {
   type BatchEmailItem,
   type BounceClass,
+  type DnsRecord,
+  type DomainStatus,
+  type DomainsCapability,
   defineEmailProvider,
   type EmailEvent,
   type EmailEventType,
@@ -27,6 +30,14 @@ export interface PostmarkConfig {
   messageStream?: string;
   /** HTTP Basic creds the webhook URL must present. Unset → webhooks rejected. */
   webhookBasicAuth?: { user: string; pass: string };
+  /**
+   * Postmark ACCOUNT API token — NOT the server token. Postmark's Domains API
+   * authenticates with `X-Postmark-Account-Token`, an account-level credential
+   * the per-server token cannot substitute for. When absent, the provider OMITS
+   * the `domains` capability entirely (the engine/CLI degrade gracefully:
+   * `supported: false`, admin domain POSTs return 501).
+   */
+  accountToken?: string;
 }
 
 /** Postmark wants comma-joined recipient strings; omit the field when empty. */
@@ -86,6 +97,13 @@ export function createPostmarkProvider(cfg: PostmarkConfig): EmailProvider {
 
   return defineEmailProvider({
     meta: { id: "postmark", name: "Postmark" },
+
+    // Sending-domain management — gated on the ACCOUNT token (the Domains API
+    // does not accept the server token). Absent ⇒ no `domains` member at all,
+    // so the engine's capability gate stays closed.
+    ...(cfg.accountToken
+      ? { domains: createPostmarkDomains({ accountToken: cfg.accountToken }) }
+      : {}),
     capabilities: {
       // Forced off per-send above → the engine TRUSTS native tracking is off.
       nativeTracking: false,
@@ -137,6 +155,191 @@ export function createPostmarkProvider(cfg: PostmarkConfig): EmailProvider {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Domains capability (Postmark account-token Domains API)
+// ---------------------------------------------------------------------------
+
+const DOMAINS_BASE_URL = "https://api.postmarkapp.com";
+
+/** A domain as Postmark's `GET /domains/:id` detail reports it. */
+interface PostmarkDomainDetail {
+  ID?: number;
+  Name?: string;
+  DKIMVerified?: boolean;
+  DKIMHost?: string;
+  DKIMTextValue?: string;
+  DKIMPendingHost?: string;
+  DKIMPendingTextValue?: string;
+  ReturnPathDomain?: string;
+  ReturnPathDomainVerified?: boolean;
+  ReturnPathDomainCNAMEValue?: string;
+}
+
+function postmarkErrorMessage(status: number, body: unknown): string {
+  if (
+    body &&
+    typeof body === "object" &&
+    "Message" in body &&
+    typeof (body as { Message: unknown }).Message === "string"
+  ) {
+    return `Postmark domains API ${status}: ${(body as { Message: string }).Message}`;
+  }
+  return `Postmark domains API request failed with status ${status}`;
+}
+
+/**
+ * Synthesize neutral {@link DnsRecord}s from a Postmark domain detail. Postmark
+ * has no records array — DKIM (a TXT, preferring the PENDING host/value during
+ * a rotation) and the Return-Path CNAME are reconstructed from the flat fields.
+ */
+function postmarkRecords(detail: PostmarkDomainDetail): DnsRecord[] {
+  const records: DnsRecord[] = [];
+
+  const dkimName = detail.DKIMPendingHost || detail.DKIMHost || "";
+  const dkimValue = detail.DKIMPendingTextValue || detail.DKIMTextValue || "";
+  if (dkimName && dkimValue) {
+    records.push({
+      type: "TXT",
+      name: dkimName,
+      value: dkimValue,
+      purpose: "dkim",
+      status: detail.DKIMVerified ? "verified" : "pending",
+    });
+  }
+
+  if (detail.ReturnPathDomain && detail.ReturnPathDomainCNAMEValue) {
+    records.push({
+      type: "CNAME",
+      name: detail.ReturnPathDomain,
+      value: detail.ReturnPathDomainCNAMEValue,
+      purpose: "return_path",
+      status: detail.ReturnPathDomainVerified ? "verified" : "pending",
+    });
+  }
+
+  return records;
+}
+
+function postmarkDomainStatus(detail: PostmarkDomainDetail): DomainStatus {
+  return {
+    domain: detail.Name ?? "",
+    // Verified ONLY when both DKIM and the return path check out — Postmark has
+    // no single domain-level status flag.
+    state:
+      detail.DKIMVerified && detail.ReturnPathDomainVerified
+        ? "verified"
+        : "pending",
+    records: postmarkRecords(detail),
+    providerId: "postmark",
+    checkedAt: new Date().toISOString(),
+    raw: detail,
+  };
+}
+
+/**
+ * The Postmark implementation of the {@link DomainsCapability} contract — a
+ * dumb wire over `https://api.postmarkapp.com/domains`, authenticated with the
+ * ACCOUNT token. Plain `fetch`, deliberately NOT the `postmark` SDK's account
+ * client (keeps the opt-in surface minimal).
+ */
+function createPostmarkDomains(cfg: {
+  accountToken: string;
+}): DomainsCapability {
+  const api = async (
+    path: string,
+    init?: { method?: string; body?: unknown },
+  ): Promise<{ ok: boolean; status: number; body: unknown }> => {
+    const res = await fetch(`${DOMAINS_BASE_URL}${path}`, {
+      method: init?.method ?? "GET",
+      headers: {
+        Accept: "application/json",
+        "X-Postmark-Account-Token": cfg.accountToken,
+        ...(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 → Postmark domain ID via `GET /domains`. */
+  const findId = async (domain: string): Promise<number | null> => {
+    const res = await api("/domains?count=500&offset=0");
+    if (!res.ok) throw new Error(postmarkErrorMessage(res.status, res.body));
+    const list =
+      res.body && typeof res.body === "object" && "Domains" in res.body
+        ? (res.body as { Domains: Array<{ ID?: number; Name?: string }> })
+            .Domains
+        : [];
+    const match = (list ?? []).find((d) => d.Name === domain);
+    return match?.ID ?? null;
+  };
+
+  /** Fetch + normalize `GET /domains/:id`. */
+  const getById = async (id: number): Promise<DomainStatus> => {
+    const res = await api(`/domains/${id}`);
+    if (!res.ok) throw new Error(postmarkErrorMessage(res.status, res.body));
+    return postmarkDomainStatus(res.body as PostmarkDomainDetail);
+  };
+
+  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 postmarkDomainStatus(res.body as PostmarkDomainDetail);
+      }
+
+      // Idempotent create: a 422 "already exists" 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 === 422 && /already exists/i.test(message)) {
+        const existing = await get(domain);
+        if (existing) return existing;
+      }
+      throw new Error(postmarkErrorMessage(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 Postmark — run create first`,
+        );
+      }
+      // Run BOTH verification passes best-effort (Postmark 422s a pass that is
+      // already verified / not yet ready); the re-get below is the truth.
+      await api(`/domains/${id}/verifyDkim`, { method: "PUT" });
+      await api(`/domains/${id}/verifyReturnPath`, { method: "PUT" });
+      return getById(id);
+    },
+  };
+}
+
 /**
  * Postmark `Bounce.TypeCode` values, mapped to provider-neutral bounce classes.
  * The raw string `Type` is preserved in `bounce.code` so nothing is lost.