@gusnips/one-click-dns 0.1.1 → 0.1.3

package/README.md

@@ -102,6 +102,22 @@ When the host has your template, `plan.methods` starts with a `domain-connect` m
 
 Only these providers are asked, because their `_domainconnect` value and settings were read from DNS: Cloudflare, Vercel, Simply.com and GoDaddy. A name in a customer's DNS is never fetched. More providers join the same way, one value at a time.
 
+### Which providers have switched your template on
+
+A merged template is not a template a provider uses. Each provider turns templates on by hand, and the only way to know is to ask it. `templateCoverage` asks every provider in the list once:
+
+```ts
+import { templateCoverage } from "@gusnips/one-click-dns/server";
+
+const coverage = await templateCoverage(
+  {},
+  { providerId: "example.com", serviceId: "custom-domain" },
+);
+// { cloudflare: "not_supported", godaddy: "supported", vercel: "not_supported", simply: "not_supported" }
+```
+
+`"unanswered"` means the provider was busy or did not reply. It never means no. Run it now and then to see when a provider starts to support your template.
+
 ## Templates
 
 A template is a small JSON file in the public [Domain Connect Templates](https://github.com/Domain-Connect/Templates) repository. It lists the records you may ask a host to add. The presets build one that follows the repository's rules:
@@ -125,6 +141,8 @@ console.log(templateFileName(template)); // "example.com.custom-domain.json"
 
 There are presets for a CNAME, DMARC, SPF, DKIM, MX and a verification TXT.
 
+Two of them change how a domain's email works. The MX preset replaces the MX records the domain has, so its mail goes somewhere else. The SPF preset adds a sender to the domain's SPF record. Ask the person for consent in your own screen before you offer either link, and say what changes in the template's `description`, which the DNS host shows when they approve.
+
 A template belongs to the company that files it. It names your key domain, and the host checks every link against the key published there. So you cannot use someone else's template, and nobody can use yours. The customer's domain is not in the template: it comes with each link, so one template serves every customer.
 
 To file a template: test it in the [online editor](https://domainconnect.paulonet.eu/dc/free/templateedit), run `dc-template-linter -merge-or-fail` on it, open a pull request, then ask each DNS host to switch it on.

package/dist/{chunk-56ZUD4EQ.js → chunk-4XNRV7QR.js}

@@ -5,22 +5,25 @@ import {
 // src/bounded-fetch.ts
 import { readBounded } from "@gusnips/server";
 async function fetchBounded(doFetch, url, init, limits) {
-  try {
-    const res = await doFetch(url, {
-      ...init,
-      redirect: "manual",
-      signal: AbortSignal.timeout(limits.timeoutMs)
-    });
-    if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
-      await res.body?.cancel().catch(() => void 0);
-      return { status: res.status || 302, text: "" };
+  const signal = AbortSignal.timeout(limits.timeoutMs);
+  const outOfTime = new Promise((resolve) => {
+    signal.addEventListener("abort", () => resolve(null), { once: true });
+  });
+  const attempt = async () => {
+    try {
+      const res = await doFetch(url, { ...init, redirect: "manual", signal });
+      if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
+        await res.body?.cancel().catch(() => void 0);
+        return { status: res.status || 302, text: "" };
+      }
+      const { bytes, truncated } = await readBounded(res.body, limits.maxBytes);
+      if (truncated) return null;
+      return { status: res.status, text: new TextDecoder().decode(bytes) };
+    } catch {
+      return null;
     }
-    const { bytes, truncated } = await readBounded(res.body, limits.maxBytes);
-    if (truncated) return null;
-    return { status: res.status, text: new TextDecoder().decode(bytes) };
-  } catch {
-    return null;
-  }
+  };
+  return Promise.race([attempt(), outOfTime]);
 }
 
 // src/guards.ts

package/dist/index.cjs

@@ -663,21 +663,24 @@ function spfTemplate(identity, options = {}) {
   );
 }
 function dkimTemplate(identity, options = {}) {
-  const keys = options.keys ?? 2;
+  const { selectors } = options;
+  const keys = selectors?.length ?? options.keys ?? 2;
   const numbers = Array.from({ length: keys }, (_, index) => index + 1);
+  const hostOf = (n) => selectors ? `${selectors[n - 1]}._domainkey` : `%selector${n}%._domainkey`;
+  const describe = (n) => selectors ? `%target${n}%: where ${selectors[n - 1]}._domainkey points` : `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`;
   return template(
     identity,
     "dkim",
     {
       serviceName: "Sign your email with our key",
       description: "Adds the CNAME records that let us sign email sent from your domain.",
-      variableDescription: numbers.map((n) => `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`).join("; ")
+      variableDescription: options.variableDescription ?? numbers.map(describe).join("; ")
     },
     options,
     numbers.map((n) => ({
       type: "CNAME",
-      host: `%selector${n}%._domainkey`,
-      pointsTo: `%target${n}%`,
+      host: hostOf(n),
+      pointsTo: options.pointsTo?.(n) ?? `%target${n}%`,
       ttl: TTL
     }))
   );

package/dist/index.d.cts

@@ -99,12 +99,24 @@ declare function dmarcTemplate(identity: TemplateIdentity, options?: Wording & {
 /** Adds one `include:` to the domain's SPF record. `SPFM` merges it into the one record the
  *  name may have; a TXT would make a second one and break SPF. The link carries `%include%`. */
 declare function spfTemplate(identity: TemplateIdentity, options?: Wording): DomainConnectTemplate;
-/** DKIM as CNAMEs, for services that publish the key on their side. The link carries
- *  `%selector1%` and `%target1%`, then the same pair numbered up to `keys`. */
+/**
+ * DKIM as CNAMEs, for services that publish the key on their side.
+ *
+ * By default the link carries `%selector1%` and `%target1%`, then the same pair numbered up to
+ * `keys`. When your key names never change, fix them: `selectors: ["cd1", "cd2"]` writes
+ * `cd1._domainkey` and `cd2._domainkey` into the template, which the repository prefers to a
+ * variable. `pointsTo` then names where each CNAME goes (`(n) => "%dkim" + n + "%.example.net"`),
+ * and `variableDescription` says what its variables mean.
+ */
 declare function dkimTemplate(identity: TemplateIdentity, options?: Wording & {
     keys?: number;
+    selectors?: readonly string[];
+    pointsTo?: (n: number) => string;
+    variableDescription?: string;
 }): DomainConnectTemplate;
-/** The MX record that sends the domain's mail to you. */
+/** The MX record that sends the domain's mail to you. It changes where the domain's email is
+ *  delivered and replaces the MX records it has, so ask the person for consent before you offer
+ *  the link; say so in `description` too. */
 declare function mxTemplate(identity: TemplateIdentity, options: Wording & {
     pointsTo: string;
     priority?: number;

package/dist/index.d.ts

@@ -99,12 +99,24 @@ declare function dmarcTemplate(identity: TemplateIdentity, options?: Wording & {
 /** Adds one `include:` to the domain's SPF record. `SPFM` merges it into the one record the
  *  name may have; a TXT would make a second one and break SPF. The link carries `%include%`. */
 declare function spfTemplate(identity: TemplateIdentity, options?: Wording): DomainConnectTemplate;
-/** DKIM as CNAMEs, for services that publish the key on their side. The link carries
- *  `%selector1%` and `%target1%`, then the same pair numbered up to `keys`. */
+/**
+ * DKIM as CNAMEs, for services that publish the key on their side.
+ *
+ * By default the link carries `%selector1%` and `%target1%`, then the same pair numbered up to
+ * `keys`. When your key names never change, fix them: `selectors: ["cd1", "cd2"]` writes
+ * `cd1._domainkey` and `cd2._domainkey` into the template, which the repository prefers to a
+ * variable. `pointsTo` then names where each CNAME goes (`(n) => "%dkim" + n + "%.example.net"`),
+ * and `variableDescription` says what its variables mean.
+ */
 declare function dkimTemplate(identity: TemplateIdentity, options?: Wording & {
     keys?: number;
+    selectors?: readonly string[];
+    pointsTo?: (n: number) => string;
+    variableDescription?: string;
 }): DomainConnectTemplate;
-/** The MX record that sends the domain's mail to you. */
+/** The MX record that sends the domain's mail to you. It changes where the domain's email is
+ *  delivered and replaces the MX records it has, so ask the person for consent before you offer
+ *  the link; say so in `description` too. */
 declare function mxTemplate(identity: TemplateIdentity, options: Wording & {
     pointsTo: string;
     priority?: number;

package/dist/index.js

@@ -117,21 +117,24 @@ function spfTemplate(identity, options = {}) {
   );
 }
 function dkimTemplate(identity, options = {}) {
-  const keys = options.keys ?? 2;
+  const { selectors } = options;
+  const keys = selectors?.length ?? options.keys ?? 2;
   const numbers = Array.from({ length: keys }, (_, index) => index + 1);
+  const hostOf = (n) => selectors ? `${selectors[n - 1]}._domainkey` : `%selector${n}%._domainkey`;
+  const describe = (n) => selectors ? `%target${n}%: where ${selectors[n - 1]}._domainkey points` : `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`;
   return template(
     identity,
     "dkim",
     {
       serviceName: "Sign your email with our key",
       description: "Adds the CNAME records that let us sign email sent from your domain.",
-      variableDescription: numbers.map((n) => `%selector${n}%: the key name, ${n} of ${keys}; %target${n}%: where it points`).join("; ")
+      variableDescription: options.variableDescription ?? numbers.map(describe).join("; ")
     },
     options,
     numbers.map((n) => ({
       type: "CNAME",
-      host: `%selector${n}%._domainkey`,
-      pointsTo: `%target${n}%`,
+      host: hostOf(n),
+      pointsTo: options.pointsTo?.(n) ?? `%target${n}%`,
       ttl: TTL
     }))
   );

package/dist/server/index.cjs

@@ -27,7 +27,8 @@ __export(server_exports, {
   readDnsZone: () => readDnsZone,
   signedApplyUrl: () => signedApplyUrl,
   systemDnsLookups: () => systemDnsLookups,
-  systemResolver: () => systemResolver
+  systemResolver: () => systemResolver,
+  templateCoverage: () => templateCoverage
 });
 module.exports = __toCommonJS(server_exports);
 
@@ -657,22 +658,25 @@ var CONNECT_PROVIDERS = [
 // src/bounded-fetch.ts
 var import_server = require("@gusnips/server");
 async function fetchBounded(doFetch, url, init, limits) {
-  try {
-    const res = await doFetch(url, {
-      ...init,
-      redirect: "manual",
-      signal: AbortSignal.timeout(limits.timeoutMs)
-    });
-    if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
-      await res.body?.cancel().catch(() => void 0);
-      return { status: res.status || 302, text: "" };
+  const signal = AbortSignal.timeout(limits.timeoutMs);
+  const outOfTime = new Promise((resolve) => {
+    signal.addEventListener("abort", () => resolve(null), { once: true });
+  });
+  const attempt = async () => {
+    try {
+      const res = await doFetch(url, { ...init, redirect: "manual", signal });
+      if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
+        await res.body?.cancel().catch(() => void 0);
+        return { status: res.status || 302, text: "" };
+      }
+      const { bytes, truncated } = await (0, import_server.readBounded)(res.body, limits.maxBytes);
+      if (truncated) return null;
+      return { status: res.status, text: new TextDecoder().decode(bytes) };
+    } catch {
+      return null;
     }
-    const { bytes, truncated } = await (0, import_server.readBounded)(res.body, limits.maxBytes);
-    if (truncated) return null;
-    return { status: res.status, text: new TextDecoder().decode(bytes) };
-  } catch {
-    return null;
-  }
+  };
+  return Promise.race([attempt(), outOfTime]);
 }
 
 // src/guards.ts
@@ -771,6 +775,25 @@ async function ask(io, args, deadline) {
   };
 }
 
+// src/server/connect/coverage.ts
+async function templateCoverage(io, args) {
+  const { providerId, serviceId, timeoutMs = 5e3, providers = CONNECT_PROVIDERS } = args;
+  const answers = await Promise.all(
+    providers.map(async (provider) => {
+      const answer = await fetchBounded(
+        io.fetch ?? fetch,
+        `${provider.api}/v2/domainTemplates/providers/${providerId}/services/${serviceId}`,
+        { method: "GET", headers: { Accept: "application/json" } },
+        { timeoutMs, maxBytes: 64 * 1024 }
+      );
+      if (answer?.status === 200) return [provider.id, "supported"];
+      if (answer?.status === 404) return [provider.id, "not_supported"];
+      return [provider.id, "unanswered"];
+    })
+  );
+  return Object.fromEntries(answers);
+}
+
 // src/server/connect/sign.ts
 var import_node_crypto = require("crypto");
 var encode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`).replace(/%20/g, "+");
@@ -1316,5 +1339,6 @@ async function planConnection(input, io) {
   readDnsZone,
   signedApplyUrl,
   systemDnsLookups,
-  systemResolver
+  systemResolver,
+  templateCoverage
 });

package/dist/server/index.d.cts

@@ -84,6 +84,18 @@ declare function discoverConnect(io: DiscoveryIo, args: {
     providers?: readonly ConnectProvider[];
 }): Promise<Discovery>;
 
+type TemplateSupport = "supported" | "not_supported" | "unanswered";
+/** The answer of each provider, by our id for it (`cloudflare`). A status that says "not now"
+ *  (429, 5xx), a failed request or a redirect is `unanswered`, never "no". */
+declare function templateCoverage(io: {
+    fetch?: FetchFn;
+}, args: {
+    providerId: string;
+    serviceId: string;
+    timeoutMs?: number;
+    providers?: readonly ConnectProvider[];
+}): Promise<Record<string, TemplateSupport>>;
+
 /** Who is asking, as the templates name it. */
 interface DomainConnectIdentity {
     /** The provider id our templates are filed under in the Templates repository
@@ -142,4 +154,4 @@ interface PlanInput {
 }
 declare function planConnection(input: PlanInput, io: DiscoveryIo & ZoneLookups): Promise<ConnectPlan>;
 
-export { CONNECT_PROVIDERS, type ConnectMethod, type ConnectPlan, type ConnectProvider, type Discovery, type DiscoveryIo, type DnsAnswer, type DnsAsk, type DnsLookups, type DomainConnectIdentity, FetchFn, type PlanInput, type ZoneLookups, discoverConnect, dnsHostOf, planConnection, readDnsZone, signedApplyUrl, systemDnsLookups, systemResolver };
+export { CONNECT_PROVIDERS, type ConnectMethod, type ConnectPlan, type ConnectProvider, type Discovery, type DiscoveryIo, type DnsAnswer, type DnsAsk, type DnsLookups, type DomainConnectIdentity, FetchFn, type PlanInput, type TemplateSupport, type ZoneLookups, discoverConnect, dnsHostOf, planConnection, readDnsZone, signedApplyUrl, systemDnsLookups, systemResolver, templateCoverage };

package/dist/server/index.d.ts

@@ -84,6 +84,18 @@ declare function discoverConnect(io: DiscoveryIo, args: {
     providers?: readonly ConnectProvider[];
 }): Promise<Discovery>;
 
+type TemplateSupport = "supported" | "not_supported" | "unanswered";
+/** The answer of each provider, by our id for it (`cloudflare`). A status that says "not now"
+ *  (429, 5xx), a failed request or a redirect is `unanswered`, never "no". */
+declare function templateCoverage(io: {
+    fetch?: FetchFn;
+}, args: {
+    providerId: string;
+    serviceId: string;
+    timeoutMs?: number;
+    providers?: readonly ConnectProvider[];
+}): Promise<Record<string, TemplateSupport>>;
+
 /** Who is asking, as the templates name it. */
 interface DomainConnectIdentity {
     /** The provider id our templates are filed under in the Templates repository
@@ -142,4 +154,4 @@ interface PlanInput {
 }
 declare function planConnection(input: PlanInput, io: DiscoveryIo & ZoneLookups): Promise<ConnectPlan>;
 
-export { CONNECT_PROVIDERS, type ConnectMethod, type ConnectPlan, type ConnectProvider, type Discovery, type DiscoveryIo, type DnsAnswer, type DnsAsk, type DnsLookups, type DomainConnectIdentity, FetchFn, type PlanInput, type ZoneLookups, discoverConnect, dnsHostOf, planConnection, readDnsZone, signedApplyUrl, systemDnsLookups, systemResolver };
+export { CONNECT_PROVIDERS, type ConnectMethod, type ConnectPlan, type ConnectProvider, type Discovery, type DiscoveryIo, type DnsAnswer, type DnsAsk, type DnsLookups, type DomainConnectIdentity, FetchFn, type PlanInput, type TemplateSupport, type ZoneLookups, discoverConnect, dnsHostOf, planConnection, readDnsZone, signedApplyUrl, systemDnsLookups, systemResolver, templateCoverage };

package/dist/server/index.js

@@ -5,7 +5,7 @@ import {
   fetchBounded,
   isObject,
   writers
-} from "../chunk-56ZUD4EQ.js";
+} from "../chunk-4XNRV7QR.js";
 import {
   normalizeDnsName
 } from "../chunk-P2O7INDB.js";
@@ -211,6 +211,25 @@ async function ask(io, args, deadline) {
   };
 }
 
+// src/server/connect/coverage.ts
+async function templateCoverage(io, args) {
+  const { providerId, serviceId, timeoutMs = 5e3, providers = CONNECT_PROVIDERS } = args;
+  const answers = await Promise.all(
+    providers.map(async (provider) => {
+      const answer = await fetchBounded(
+        io.fetch ?? fetch,
+        `${provider.api}/v2/domainTemplates/providers/${providerId}/services/${serviceId}`,
+        { method: "GET", headers: { Accept: "application/json" } },
+        { timeoutMs, maxBytes: 64 * 1024 }
+      );
+      if (answer?.status === 200) return [provider.id, "supported"];
+      if (answer?.status === 404) return [provider.id, "not_supported"];
+      return [provider.id, "unanswered"];
+    })
+  );
+  return Object.fromEntries(answers);
+}
+
 // src/server/connect/sign.ts
 import { createPrivateKey, sign } from "crypto";
 var encode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`).replace(/%20/g, "+");
@@ -270,5 +289,6 @@ export {
   readDnsZone,
   signedApplyUrl,
   systemDnsLookups,
-  systemResolver
+  systemResolver,
+  templateCoverage
 };

package/dist/writers/index.cjs

@@ -32,22 +32,25 @@ module.exports = __toCommonJS(writers_exports);
 // src/bounded-fetch.ts
 var import_server = require("@gusnips/server");
 async function fetchBounded(doFetch, url, init, limits) {
-  try {
-    const res = await doFetch(url, {
-      ...init,
-      redirect: "manual",
-      signal: AbortSignal.timeout(limits.timeoutMs)
-    });
-    if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
-      await res.body?.cancel().catch(() => void 0);
-      return { status: res.status || 302, text: "" };
+  const signal = AbortSignal.timeout(limits.timeoutMs);
+  const outOfTime = new Promise((resolve) => {
+    signal.addEventListener("abort", () => resolve(null), { once: true });
+  });
+  const attempt = async () => {
+    try {
+      const res = await doFetch(url, { ...init, redirect: "manual", signal });
+      if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
+        await res.body?.cancel().catch(() => void 0);
+        return { status: res.status || 302, text: "" };
+      }
+      const { bytes, truncated } = await (0, import_server.readBounded)(res.body, limits.maxBytes);
+      if (truncated) return null;
+      return { status: res.status, text: new TextDecoder().decode(bytes) };
+    } catch {
+      return null;
     }
-    const { bytes, truncated } = await (0, import_server.readBounded)(res.body, limits.maxBytes);
-    if (truncated) return null;
-    return { status: res.status, text: new TextDecoder().decode(bytes) };
-  } catch {
-    return null;
-  }
+  };
+  return Promise.race([attempt(), outOfTime]);
 }
 
 // src/dns-name.ts

package/dist/writers/index.js

@@ -5,7 +5,7 @@ import {
   namecom,
   porkbun,
   writers
-} from "../chunk-56ZUD4EQ.js";
+} from "../chunk-4XNRV7QR.js";
 import "../chunk-P2O7INDB.js";
 export {
   DnsWriteError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/one-click-dns",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "packageManager": "bun@1.4.2",
   "description": "Put DNS records in a customer's zone: find their DNS host, send them to a signed Domain Connect link, write with an API token, or show the steps for that host",
   "type": "module",