supersendtx 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -53,13 +53,89 @@ type SuperSendTXOptions = {
     baseUrl?: string;
     fetch?: typeof fetch;
 };
+type DomainStatus = 'pending' | 'verified' | 'failed';
+type Domain = {
+    id: string;
+    name: string;
+    status: DomainStatus | string;
+    created_at: string;
+    verified_at: string | null;
+};
+type DnsRecord = {
+    type: string;
+    host: string;
+    value: string;
+    purpose: string;
+};
+type CreateDomainParams = {
+    name: string;
+};
+type CreateDomainResult = {
+    domain: Domain;
+    records: DnsRecord[];
+};
+type VerifyDomainResult = {
+    domain: Domain;
+    records: DnsRecord[];
+    verified: boolean;
+    checks?: {
+        ownership: boolean;
+        spf: boolean;
+        dkim: boolean;
+        dmarc: boolean;
+    };
+    auto?: boolean;
+};
+type DnsProviderName$1 = 'cloudflare' | 'godaddy';
+type ApplyDnsParams = {
+    provider: DnsProviderName$1;
+    /** Domain id or name (fetched from SuperSend TX for DNS records). */
+    idOrName: string;
+    cloudflareApiToken?: string;
+    cloudflareZoneId?: string;
+    godaddyApiKey?: string;
+    godaddyApiSecret?: string;
+};
+type ApplyDnsRecordResult$1 = {
+    purpose: string;
+    host: string;
+    action: 'created' | 'updated' | 'unchanged' | 'merged';
+    detail?: string;
+};
+type ApplyDnsResult$1 = {
+    provider: DnsProviderName$1;
+    domain: string;
+    results: ApplyDnsRecordResult$1[];
+};
 type ApiErrorBody = {
-    error?: {
+    error?: string | {
         message?: string;
         details?: unknown;
     };
 };
 
+declare class DomainsResource {
+    private readonly client;
+    constructor(client: SuperSendTX);
+    list(): Promise<{
+        domains: Domain[];
+    }>;
+    get(idOrName: string): Promise<{
+        domain: Domain;
+        records: DnsRecord[];
+    }>;
+    create(params: CreateDomainParams): Promise<CreateDomainResult>;
+    verify(idOrName: string): Promise<VerifyDomainResult>;
+    delete(idOrName: string): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Fetch SuperSend TX DNS records, then write them at Cloudflare or GoDaddy
+     * using the caller's provider credentials (never sent to SuperSend TX).
+     */
+    applyDns(params: ApplyDnsParams): Promise<ApplyDnsResult$1>;
+}
+
 declare class EmailsResource {
     private readonly client;
     constructor(client: SuperSendTX);
@@ -85,6 +161,7 @@ declare const DEFAULT_API_BASE_URL = "https://api.supersendtx.com";
 declare class SuperSendTX {
     private readonly apiKey;
     private readonly options;
+    readonly domains: DomainsResource;
     readonly emails: EmailsResource;
     readonly webhooks: WebhooksResource;
     constructor(apiKey: string, options?: SuperSendTXOptions);
@@ -100,4 +177,34 @@ declare class SuperSendTXError extends Error {
     static fromResponse(status: number, body: ApiErrorBody): SuperSendTXError;
 }
 
-export { type CreateWebhookParams, DEFAULT_API_BASE_URL, type EmailListItem, type ListEmailsParams, type SendEmailParams, type SendEmailResult, SuperSendTX, SuperSendTXError, type SuperSendTXOptions, type WebhookEndpoint, type WebhookEndpointWithSecret, type WebhookEventType };
+/** Merge `include:host` into an existing SPF record (or create a minimal one). */
+declare function mergeSpfInclude(existing: string | null | undefined, includeHost: string): string;
+
+type DnsProviderName = 'cloudflare' | 'godaddy';
+type ApplyDnsRecordResult = {
+    purpose: string;
+    host: string;
+    action: 'created' | 'updated' | 'unchanged' | 'merged';
+    detail?: string;
+};
+type ApplyDnsResult = {
+    provider: DnsProviderName;
+    domain: string;
+    results: ApplyDnsRecordResult[];
+};
+type ApplyDnsCredentials = {
+    cloudflareApiToken?: string;
+    cloudflareZoneId?: string;
+    godaddyApiKey?: string;
+    godaddyApiSecret?: string;
+};
+
+declare function applyDnsRecords(input: {
+    provider: DnsProviderName;
+    domain: string;
+    records: DnsRecord[];
+    credentials: ApplyDnsCredentials;
+    fetchImpl?: typeof fetch;
+}): Promise<ApplyDnsResult>;
+
+export { type ApplyDnsParams, type ApplyDnsRecordResult$1 as ApplyDnsRecordResult, type ApplyDnsResult$1 as ApplyDnsResult, type CreateDomainParams, type CreateDomainResult, type CreateWebhookParams, DEFAULT_API_BASE_URL, type DnsProviderName$1 as DnsProviderName, type DnsRecord, type Domain, type DomainStatus, type EmailListItem, type ListEmailsParams, type SendEmailParams, type SendEmailResult, SuperSendTX, SuperSendTXError, type SuperSendTXOptions, type VerifyDomainResult, type WebhookEndpoint, type WebhookEndpointWithSecret, type WebhookEventType, applyDnsRecords, mergeSpfInclude };

package/dist/index.js

@@ -7,8 +7,377 @@ var SuperSendTXError = class _SuperSendTXError extends Error {
     this.details = details;
   }
   static fromResponse(status, body) {
-    const message = body.error?.message || `Request failed with status ${status}`;
-    return new _SuperSendTXError(message, status, body.error?.details);
+    const err = body.error;
+    const message = typeof err === "string" ? err : err?.message || `Request failed with status ${status}`;
+    const details = typeof err === "object" && err ? err.details : void 0;
+    return new _SuperSendTXError(message, status, details);
+  }
+};
+
+// src/dns/spf.ts
+function mergeSpfInclude(existing, includeHost) {
+  const include = `include:${includeHost.replace(/^include:/i, "")}`;
+  const trimmed = existing?.trim();
+  if (!trimmed) {
+    return `v=spf1 ${include} ~all`;
+  }
+  if (trimmed.toLowerCase().includes(include.toLowerCase())) {
+    return trimmed;
+  }
+  if (!/^v=spf1\b/i.test(trimmed)) {
+    return `v=spf1 ${include} ~all`;
+  }
+  if (/\s[~?+\-]all\s*$/i.test(trimmed)) {
+    return trimmed.replace(/\s([~?+\-]all)\s*$/i, ` ${include} $1`);
+  }
+  return `${trimmed} ${include} ~all`;
+}
+function isSpfRecord(value) {
+  return value.trim().toLowerCase().startsWith("v=spf1");
+}
+
+// src/dns/cloudflare.ts
+function relativeName(fqdn, zone) {
+  const domain = zone.replace(/\.$/, "").toLowerCase();
+  const host = fqdn.replace(/\.$/, "").toLowerCase();
+  if (host === domain) return "@";
+  if (host.endsWith(`.${domain}`)) return host.slice(0, -(domain.length + 1));
+  return host;
+}
+function createCloudflareProvider(options) {
+  const fetchImpl = options.fetchImpl || fetch;
+  const headers = {
+    Authorization: `Bearer ${options.apiToken}`,
+    "Content-Type": "application/json"
+  };
+  async function cf(path, init) {
+    const response = await fetchImpl(`https://api.cloudflare.com/client/v4${path}`, {
+      ...init,
+      headers: { ...headers, ...init?.headers || {} }
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok || body.success === false) {
+      const message = body.errors?.map((e) => e.message).filter(Boolean).join("; ") || `Cloudflare HTTP ${response.status}`;
+      throw new Error(message);
+    }
+    return body.result;
+  }
+  async function resolveZoneId(domain) {
+    if (options.zoneId) return options.zoneId;
+    const zones = await cf(`/zones?name=${encodeURIComponent(domain)}&status=active`);
+    const zone = zones?.[0];
+    if (!zone) {
+      throw new Error(`No active Cloudflare zone found for ${domain}`);
+    }
+    return zone.id;
+  }
+  return {
+    name: "cloudflare",
+    async apply(domain, records) {
+      const zoneId = await resolveZoneId(domain);
+      const zoneName = domain.toLowerCase();
+      const results = [];
+      for (const record of records) {
+        if (record.type.toUpperCase() !== "TXT") {
+          results.push({
+            purpose: record.purpose,
+            host: record.host,
+            action: "unchanged",
+            detail: `Skipped unsupported type ${record.type}`
+          });
+          continue;
+        }
+        const name = relativeName(record.host, zoneName);
+        const absoluteName = name === "@" ? zoneName : `${name}.${zoneName}`;
+        if (record.purpose === "SPF") {
+          const allTxt = await cf(
+            `/zones/${zoneId}/dns_records?type=TXT&name=${encodeURIComponent(zoneName)}&per_page=100`
+          );
+          const spfRecords = (allTxt || []).filter((r) => isSpfRecord(r.content));
+          const existing = spfRecords[0];
+          const includeHost = record.value.match(/include:([^\s]+)/i)?.[1] || "spf.supersendtx.com";
+          const merged = mergeSpfInclude(existing?.content, includeHost);
+          if (existing) {
+            if (existing.content.trim() === merged.trim()) {
+              results.push({
+                purpose: record.purpose,
+                host: record.host,
+                action: "unchanged",
+                detail: "SPF already includes SuperSend TX"
+              });
+            } else {
+              await cf(`/zones/${zoneId}/dns_records/${existing.id}`, {
+                method: "PUT",
+                body: JSON.stringify({
+                  type: "TXT",
+                  name: zoneName,
+                  content: merged,
+                  ttl: 1
+                })
+              });
+              results.push({
+                purpose: record.purpose,
+                host: record.host,
+                action: "merged",
+                detail: merged
+              });
+            }
+          } else {
+            await cf(`/zones/${zoneId}/dns_records`, {
+              method: "POST",
+              body: JSON.stringify({
+                type: "TXT",
+                name: zoneName,
+                content: merged,
+                ttl: 1
+              })
+            });
+            results.push({
+              purpose: record.purpose,
+              host: record.host,
+              action: "created",
+              detail: merged
+            });
+          }
+          continue;
+        }
+        const existingList = await cf(
+          `/zones/${zoneId}/dns_records?type=TXT&name=${encodeURIComponent(absoluteName)}&per_page=100`
+        );
+        const match = (existingList || []).find((r) => r.content === record.value);
+        if (match) {
+          results.push({
+            purpose: record.purpose,
+            host: record.host,
+            action: "unchanged"
+          });
+          continue;
+        }
+        const replaceable = (existingList || []).find((r) => {
+          if (record.purpose === "Domain ownership") return r.content.includes("supersendtx-verify=");
+          if (record.purpose === "DKIM") return r.content.toLowerCase().includes("v=dkim1");
+          if (record.purpose === "DMARC") return r.content.toLowerCase().includes("v=dmarc1");
+          return false;
+        });
+        if (replaceable) {
+          await cf(`/zones/${zoneId}/dns_records/${replaceable.id}`, {
+            method: "PUT",
+            body: JSON.stringify({
+              type: "TXT",
+              name: absoluteName,
+              content: record.value,
+              ttl: 1
+            })
+          });
+          results.push({ purpose: record.purpose, host: record.host, action: "updated" });
+        } else {
+          await cf(`/zones/${zoneId}/dns_records`, {
+            method: "POST",
+            body: JSON.stringify({
+              type: "TXT",
+              name: absoluteName,
+              content: record.value,
+              ttl: 1
+            })
+          });
+          results.push({ purpose: record.purpose, host: record.host, action: "created" });
+        }
+      }
+      return results;
+    }
+  };
+}
+
+// src/dns/godaddy.ts
+function relativeName2(fqdn, zone) {
+  const domain = zone.replace(/\.$/, "").toLowerCase();
+  const host = fqdn.replace(/\.$/, "").toLowerCase();
+  if (host === domain) return "@";
+  if (host.endsWith(`.${domain}`)) return host.slice(0, -(domain.length + 1));
+  return host;
+}
+function createGoDaddyProvider(options) {
+  const fetchImpl = options.fetchImpl || fetch;
+  const headers = {
+    Authorization: `sso-key ${options.apiKey}:${options.apiSecret}`,
+    "Content-Type": "application/json",
+    Accept: "application/json"
+  };
+  async function gd(path, init) {
+    const response = await fetchImpl(`https://api.godaddy.com${path}`, {
+      ...init,
+      headers: { ...headers, ...init?.headers || {} }
+    });
+    if (response.status === 204) return void 0;
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const message = body.message || (Array.isArray(body.errors) ? body.errors.map((e) => e.message).join("; ") : null) || `GoDaddy HTTP ${response.status}`;
+      throw new Error(message);
+    }
+    return body;
+  }
+  return {
+    name: "godaddy",
+    async apply(domain, records) {
+      const zone = domain.toLowerCase();
+      const results = [];
+      for (const record of records) {
+        if (record.type.toUpperCase() !== "TXT") {
+          results.push({
+            purpose: record.purpose,
+            host: record.host,
+            action: "unchanged",
+            detail: `Skipped unsupported type ${record.type}`
+          });
+          continue;
+        }
+        const name = relativeName2(record.host, zone);
+        if (record.purpose === "SPF") {
+          const existing2 = await gd(`/v1/domains/${zone}/records/TXT/${encodeURIComponent(name)}`);
+          const list2 = existing2 || [];
+          const spfIndex = list2.findIndex((r) => isSpfRecord(r.data));
+          const includeHost = record.value.match(/include:([^\s]+)/i)?.[1] || "spf.supersendtx.com";
+          const currentSpf = spfIndex >= 0 ? list2[spfIndex].data : null;
+          const merged = mergeSpfInclude(currentSpf, includeHost);
+          if (spfIndex >= 0 && list2[spfIndex].data.trim() === merged.trim()) {
+            results.push({
+              purpose: record.purpose,
+              host: record.host,
+              action: "unchanged",
+              detail: "SPF already includes SuperSend TX"
+            });
+            continue;
+          }
+          const next2 = list2.map(
+            (r, i) => i === spfIndex ? { type: "TXT", name, data: merged, ttl: Math.max(r.ttl || 600, 600) } : r
+          );
+          if (spfIndex < 0) {
+            next2.push({ type: "TXT", name, data: merged, ttl: 600 });
+          }
+          await gd(`/v1/domains/${zone}/records/TXT/${encodeURIComponent(name)}`, {
+            method: "PUT",
+            body: JSON.stringify(next2.map(({ type, name: n, data, ttl }) => ({ type, name: n, data, ttl })))
+          });
+          results.push({
+            purpose: record.purpose,
+            host: record.host,
+            action: spfIndex >= 0 ? "merged" : "created",
+            detail: merged
+          });
+          continue;
+        }
+        const existing = await gd(`/v1/domains/${zone}/records/TXT/${encodeURIComponent(name)}`);
+        const list = existing || [];
+        const exact = list.find((r) => r.data === record.value);
+        if (exact) {
+          results.push({ purpose: record.purpose, host: record.host, action: "unchanged" });
+          continue;
+        }
+        const replaceableIndex = list.findIndex((r) => {
+          if (record.purpose === "Domain ownership") return r.data.includes("supersendtx-verify=");
+          if (record.purpose === "DKIM") return r.data.toLowerCase().includes("v=dkim1");
+          if (record.purpose === "DMARC") return r.data.toLowerCase().includes("v=dmarc1");
+          return false;
+        });
+        const next = replaceableIndex >= 0 ? list.map(
+          (r, i) => i === replaceableIndex ? { type: "TXT", name, data: record.value, ttl: Math.max(r.ttl || 600, 600) } : r
+        ) : [...list, { type: "TXT", name, data: record.value, ttl: 600 }];
+        await gd(`/v1/domains/${zone}/records/TXT/${encodeURIComponent(name)}`, {
+          method: "PUT",
+          body: JSON.stringify(next.map(({ type, name: n, data, ttl }) => ({ type, name: n, data, ttl })))
+        });
+        results.push({
+          purpose: record.purpose,
+          host: record.host,
+          action: replaceableIndex >= 0 ? "updated" : "created"
+        });
+      }
+      return results;
+    }
+  };
+}
+
+// src/dns/apply.ts
+function createDnsProvider(provider, credentials, fetchImpl) {
+  if (provider === "cloudflare") {
+    const token = credentials.cloudflareApiToken;
+    if (!token) {
+      throw new Error("Missing Cloudflare token. Set CLOUDFLARE_API_TOKEN or pass cloudflareApiToken.");
+    }
+    return createCloudflareProvider({
+      apiToken: token,
+      zoneId: credentials.cloudflareZoneId,
+      fetchImpl
+    });
+  }
+  if (provider === "godaddy") {
+    const apiKey = credentials.godaddyApiKey;
+    const apiSecret = credentials.godaddyApiSecret;
+    if (!apiKey || !apiSecret) {
+      throw new Error(
+        "Missing GoDaddy credentials. Set GODADDY_API_KEY and GODADDY_API_SECRET."
+      );
+    }
+    return createGoDaddyProvider({ apiKey, apiSecret, fetchImpl });
+  }
+  throw new Error(`Unsupported DNS provider: ${provider}`);
+}
+async function applyDnsRecords(input) {
+  const provider = createDnsProvider(input.provider, input.credentials, input.fetchImpl);
+  const results = await provider.apply(input.domain, input.records);
+  return {
+    provider: input.provider,
+    domain: input.domain,
+    results
+  };
+}
+
+// src/domains.ts
+var DomainsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async list() {
+    return this.client.request("/domains", { method: "GET" });
+  }
+  async get(idOrName) {
+    return this.client.request(`/domains/${encodeURIComponent(idOrName)}`, { method: "GET" });
+  }
+  async create(params) {
+    return this.client.request("/domains", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async verify(idOrName) {
+    return this.client.request(`/domains/${encodeURIComponent(idOrName)}`, {
+      method: "POST",
+      body: JSON.stringify({ action: "verify" })
+    });
+  }
+  async delete(idOrName) {
+    return this.client.request(`/domains/${encodeURIComponent(idOrName)}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Fetch SuperSend TX DNS records, then write them at Cloudflare or GoDaddy
+   * using the caller's provider credentials (never sent to SuperSend TX).
+   */
+  async applyDns(params) {
+    const { domain, records } = await this.get(params.idOrName);
+    return applyDnsRecords({
+      provider: params.provider,
+      domain: domain.name,
+      records,
+      credentials: {
+        cloudflareApiToken: params.cloudflareApiToken,
+        cloudflareZoneId: params.cloudflareZoneId,
+        godaddyApiKey: params.godaddyApiKey,
+        godaddyApiSecret: params.godaddyApiSecret
+      },
+      fetchImpl: this.client.fetchImpl
+    });
   }
 };
 
@@ -70,6 +439,7 @@ var SuperSendTX = class {
     if (!apiKey?.startsWith("stx_")) {
       throw new Error("SuperSend TX API key must start with stx_");
     }
+    this.domains = new DomainsResource(this);
     this.emails = new EmailsResource(this);
     this.webhooks = new WebhooksResource(this);
   }
@@ -98,5 +468,7 @@ var SuperSendTX = class {
 export {
   DEFAULT_API_BASE_URL,
   SuperSendTX,
-  SuperSendTXError
+  SuperSendTXError,
+  applyDnsRecords,
+  mergeSpfInclude
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supersendtx",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SuperSend TX transactional email API client",
   "license": "MIT",
   "type": "module",