@gusnips/one-click-dns 0.1.2 → 0.1.3

package/README.md

@@ -141,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/one-click-dns",
-  "version": "0.1.2",
+  "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",