@hogsend/core 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "drizzle-orm": "^0.45.2",
     "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.11.0"
+    "@hogsend/db": "^0.12.1"
   },
   "devDependencies": {
     "@types/node": "latest",

package/src/providers/domains.test.ts

@@ -0,0 +1,104 @@
+import { describe, expectTypeOf, it } from "vitest";
+import type {
+  DnsRecord,
+  DnsRecordPurpose,
+  DnsRecordStatus,
+  DomainStatus,
+  DomainsCapability,
+  DomainVerificationState,
+} from "./domains.js";
+import { defineEmailProvider, type EmailProvider } from "./email.js";
+
+describe("DnsRecord contract (pinned in PROJECT_SPEC §a)", () => {
+  it("pins the literal unions", () => {
+    expectTypeOf<DnsRecordPurpose>().toEqualTypeOf<
+      | "verification"
+      | "spf"
+      | "dkim"
+      | "return_path"
+      | "tracking"
+      | "mx"
+      | "other"
+    >();
+    expectTypeOf<DnsRecordStatus>().toEqualTypeOf<
+      "pending" | "verified" | "failed" | "unknown"
+    >();
+    expectTypeOf<DnsRecord["type"]>().toEqualTypeOf<"TXT" | "CNAME" | "MX">();
+    expectTypeOf<DnsRecord["name"]>().toEqualTypeOf<string>();
+    expectTypeOf<DnsRecord["value"]>().toEqualTypeOf<string>();
+    expectTypeOf<DnsRecord["ttl"]>().toEqualTypeOf<number | undefined>();
+    expectTypeOf<DnsRecord["priority"]>().toEqualTypeOf<number | undefined>();
+    expectTypeOf<DnsRecord["purpose"]>().toEqualTypeOf<DnsRecordPurpose>();
+    expectTypeOf<DnsRecord["status"]>().toEqualTypeOf<DnsRecordStatus>();
+  });
+});
+
+describe("DomainStatus contract", () => {
+  it("pins the verification state union + member types", () => {
+    expectTypeOf<DomainVerificationState>().toEqualTypeOf<
+      "not_found" | "pending" | "verified" | "failed"
+    >();
+    expectTypeOf<DomainStatus["domain"]>().toEqualTypeOf<string>();
+    expectTypeOf<
+      DomainStatus["state"]
+    >().toEqualTypeOf<DomainVerificationState>();
+    expectTypeOf<DomainStatus["records"]>().toEqualTypeOf<DnsRecord[]>();
+    expectTypeOf<DomainStatus["providerId"]>().toEqualTypeOf<string>();
+    expectTypeOf<DomainStatus["checkedAt"]>().toEqualTypeOf<string>();
+    expectTypeOf<DomainStatus["raw"]>().toEqualTypeOf<unknown>();
+  });
+});
+
+describe("DomainsCapability contract", () => {
+  it("pins the method signatures", () => {
+    expectTypeOf<DomainsCapability["create"]>().toEqualTypeOf<
+      (domain: string) => Promise<DomainStatus>
+    >();
+    expectTypeOf<DomainsCapability["get"]>().toEqualTypeOf<
+      (domain: string) => Promise<DomainStatus | null>
+    >();
+    expectTypeOf<DomainsCapability["records"]>().toEqualTypeOf<
+      (domain: string) => Promise<DnsRecord[]>
+    >();
+    expectTypeOf<DomainsCapability["verify"]>().toEqualTypeOf<
+      ((domain: string) => Promise<DomainStatus>) | undefined
+    >();
+  });
+
+  it("is an OPTIONAL EmailProvider member — presence is the capability gate", () => {
+    expectTypeOf<EmailProvider["domains"]>().toEqualTypeOf<
+      DomainsCapability | undefined
+    >();
+  });
+
+  it("round-trips through defineEmailProvider", () => {
+    const status: DomainStatus = {
+      domain: "mysite.com",
+      state: "pending",
+      records: [],
+      providerId: "fake",
+      checkedAt: new Date().toISOString(),
+    };
+    const domains: DomainsCapability = {
+      create: async () => status,
+      get: async () => null,
+      records: async () => [],
+      verify: async () => status,
+    };
+    const provider = defineEmailProvider({
+      meta: { id: "fake", name: "Fake" },
+      send: async () => ({ id: "1" }),
+      sendBatch: async () => ({ results: [] }),
+      verifyWebhook: () => {
+        throw new Error("unused");
+      },
+      parseWebhook: () => {
+        throw new Error("unused");
+      },
+      domains,
+    });
+    expectTypeOf(provider.domains).toEqualTypeOf<
+      DomainsCapability | undefined
+    >();
+  });
+});

package/src/providers/domains.ts

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// Provider-neutral sending-domain contract (the OPTIONAL `domains` capability)
+// ---------------------------------------------------------------------------
+
+/**
+ * What a DNS record is FOR, provider-neutrally. Each provider's domains
+ * implementation maps its own labels onto this union (Resend: SPF/DKIM record
+ * kinds; Postmark: DKIM + Return-Path). `other` is the conservative fallback
+ * for anything a provider invents that has no neutral name yet.
+ */
+export type DnsRecordPurpose =
+  | "verification"
+  | "spf"
+  | "dkim"
+  | "return_path"
+  | "tracking"
+  | "mx"
+  | "other";
+
+/**
+ * Per-record verification status as the PROVIDER reports it. `unknown` is for
+ * providers that don't report per-record status at all — the overall
+ * {@link DomainStatus.state} remains the authoritative signal.
+ */
+export type DnsRecordStatus = "pending" | "verified" | "failed" | "unknown";
+
+/**
+ * One DNS record the operator must add at their DNS host. This is the neutral
+ * shape every surface renders (admin route, `hogsend domain`, Studio Setup) and
+ * the CLI auto-apply (`dns-apply.ts`) writes via the Cloudflare/Vercel APIs.
+ */
+export interface DnsRecord {
+  type: "TXT" | "CNAME" | "MX";
+  /** Host as the provider reports it (may be relative, e.g. "resend._domainkey"). */
+  name: string;
+  value: string;
+  ttl?: number;
+  /** MX only. */
+  priority?: number;
+  purpose: DnsRecordPurpose;
+  status: DnsRecordStatus;
+}
+
+/**
+ * Overall domain verification state. `not_found` means the provider does not
+ * know the domain (it was never created there); the engine also reports it
+ * when the capability is supported but the domain hasn't been added yet.
+ */
+export type DomainVerificationState =
+  | "not_found"
+  | "pending"
+  | "verified"
+  | "failed";
+
+/**
+ * The provider-neutral snapshot of one sending domain: its overall state plus
+ * the DNS records required to verify it. Returned by every
+ * {@link DomainsCapability} method that resolves a domain.
+ */
+export interface DomainStatus {
+  domain: string;
+  state: DomainVerificationState;
+  records: DnsRecord[];
+  /** {@link EmailProviderMeta.id} of the provider that produced this status. */
+  providerId: string;
+  /** ISO 8601 instant this status was fetched from the provider. */
+  checkedAt: string;
+  /** The untouched provider payload, for debugging / escape hatch. */
+  raw?: unknown;
+}
+
+/**
+ * Optional provider capability for managing sending domains. PRESENCE IS THE
+ * GATE: a provider that cannot manage domains simply omits the member, and the
+ * engine/CLI/Studio degrade gracefully (admin POSTs return 501
+ * `provider_unsupported`, `EngineDomainStatus.supported` is `false`).
+ *
+ * Like the send wire, this is a DUMB translation layer: plain HTTP against the
+ * provider's domains API, normalized into {@link DomainStatus}/{@link DnsRecord}.
+ * Caching, env derivation, and test-mode policy all live in the engine's
+ * `DomainStatusService` — never here.
+ */
+export interface DomainsCapability {
+  /**
+   * Register the domain with the provider. IDEMPOTENT: when the domain already
+   * exists there, implementations fall through to a lookup and return the
+   * existing status rather than throwing.
+   */
+  create(domain: string): Promise<DomainStatus>;
+  /** Current status, or `null` when the provider doesn't know the domain. */
+  get(domain: string): Promise<DomainStatus | null>;
+  /** The DNS records required to verify the domain. */
+  records(domain: string): Promise<DnsRecord[]>;
+  /**
+   * Trigger a provider-side verification pass where supported (e.g. Resend's
+   * `POST /domains/:id/verify`). Providers without an explicit verify endpoint
+   * omit this; callers fall back to `get`.
+   */
+  verify?(domain: string): Promise<DomainStatus>;
+}

package/src/providers/email.ts

@@ -1,3 +1,5 @@
+import type { DomainsCapability } from "./domains.js";
+
 // ---------------------------------------------------------------------------
 // Send options (HTML-only wire — NO React)
 // ---------------------------------------------------------------------------
@@ -292,6 +294,13 @@ export interface EmailProvider {
    * is treated conservatively (no native tracking assumed, no scheduled send).
    */
   readonly capabilities?: EmailProviderCapabilities;
+  /**
+   * Optional sending-domain management capability ({@link DomainsCapability}).
+   * PRESENCE IS THE GATE — no `capabilities` flag mirrors it. Absent ⇒ the
+   * engine's domain-status service reports `supported: false` and the admin
+   * domain POSTs return 501; everything else degrades gracefully.
+   */
+  readonly domains?: DomainsCapability;
 
   /** Deliver a single message. Returns the provider message id. */
   send(options: SendEmailOptions): Promise<SendResult>;

package/src/providers/index.ts

@@ -1,2 +1,3 @@
 export * from "./analytics.js";
+export * from "./domains.js";
 export * from "./email.js";