@startanaicompany/dns 1.3.0

package/index.js

@@ -0,0 +1,675 @@
+'use strict';
+
+/**
+ * @startanaicompany/saac_dns
+ * Programmatic Domain Registration, DNS Management & CLI Toolkit
+ *
+ * Usage:
+ *   const dns = require('@startanaicompany/saac_dns');
+ *   // Set env vars: SAAC_USER_API_KEY and SAAC_USER_EMAIL
+ *   const results = await dns.search(['mycompany.com', 'mycompany.io']);
+ *   await dns.buy('mycompany.io', { years: 1, privacy: true, autoRenew: true });
+ *   await dns.records.add('mycompany.io', { type: 'A', host: '@', value: '1.2.3.4' });
+ */
+
+const { request, ensureRegistered } = require('./lib/client');
+
+// ─── Domain Search & Registration ──────────────────────────────────────────
+
+/**
+ * Search domain availability and pricing
+ * @param {string[]} domains - Array of domain names to search
+ * @returns {Promise<Array<{fqdn, available, price, currency, tld}>>}
+ */
+async function search(domains) {
+  if (!Array.isArray(domains)) domains = [domains];
+  // Validate domain format
+  const DOMAIN_REGEX = /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
+  for (const domain of domains) {
+    if (!domain || typeof domain !== 'string') {
+      const err = new Error(`Invalid domain: "${domain}". Domain must be a non-empty string.`);
+      err.name = 'ValidationError';
+      err.code = 108;
+      throw err;
+    }
+    if (!DOMAIN_REGEX.test(domain.trim())) {
+      const err = new Error(`Invalid domain format: "${domain}". Must be a valid FQDN like "example.com".`);
+      err.name = 'ValidationError';
+      err.code = 108;
+      throw err;
+    }
+  }
+  const results = [];
+  for (const domain of domains) {
+    const data = await request('GET', `/v1/domains/search?q=${encodeURIComponent(domain.trim())}`);
+    results.push(...(data.results || []));
+  }
+  return results;
+}
+
+/**
+ * Register a domain
+ * @param {string} domain - FQDN to register (e.g. 'mycompany.io')
+ * @param {Object} opts - Options: years, privacy, autoRenew
+ */
+async function buy(domain, opts = {}) {
+  const { years = 1, privacy = false, autoRenew = true } = opts;
+  return request('POST', '/v1/domains/register', {
+    fqdn: domain,
+    years,
+    privacy,
+    auto_renew: autoRenew
+  });
+}
+
+/**
+ * Confirm a pending domain purchase using the token from buy()
+ * @param {string} token - Confirmation token received from buy()
+ */
+async function confirmPurchase(token) {
+  if (!token) throw new Error('token is required');
+  return request('POST', '/v1/domains/confirm', { token });
+}
+
+/**
+ * Register an expiring/dropped domain (drop-catching)
+ * @param {string} domain - FQDN to catch
+ * @param {Object} opts - years, privacy, autoRenew
+ */
+async function buyDrop(domain, opts = {}) {
+  const { years = 1, privacy = false, autoRenew = true } = opts;
+  return request('POST', '/v1/domains/drop-register', { fqdn: domain, years, privacy, auto_renew: autoRenew });
+}
+
+/**
+ * List all domains for the authenticated user
+ */
+async function list() {
+  const data = await request('GET', '/v1/users/me/domains');
+  return data.domains || [];
+}
+
+/**
+ * Get domain info
+ * @param {string} domain
+ */
+async function info(domain) {
+  return request('GET', `/v1/domains/${domain}`);
+}
+
+/**
+ * Get domain prices for given TLDs
+ * @param {string[]} tlds - e.g. ['.com', '.io']
+ */
+async function prices(tlds) {
+  const data = await request('GET', '/v1/domains/prices');
+  if (!tlds || !tlds.length) return data;
+  return Object.fromEntries(Object.entries(data).filter(([k]) => tlds.includes(k)));
+}
+
+/**
+ * Renew a domain
+ * @param {string} domain
+ * @param {number} years
+ */
+async function renew(domain, years = 1) {
+  return request('POST', `/v1/domains/${domain}/renew`, { years });
+}
+
+// ─── DNS Records ─────────────────────────────────────────────────────────────
+
+const records = {
+  /**
+   * List DNS records for a domain
+   * @param {string} domain
+   */
+  list(domain) {
+    return request('GET', `/v1/dns/records?domain=${encodeURIComponent(domain)}`).then(d => d.records || []);
+  },
+
+  /**
+   * Add a DNS record
+   * @param {string} domain
+   * @param {Object} record - {type, name/host, value, ttl, priority}
+   */
+  add(domain, record) {
+    return request('POST', '/v1/dns/records', {
+      domain,
+      type: record.type,
+      name: record.host || record.name || '@',
+      value: record.value,
+      ttl: record.ttl || 300,
+      priority: record.priority
+    });
+  },
+
+  /**
+   * Update a DNS record
+   * @param {string} domain
+   * @param {string} id - Record ID
+   * @param {Object} record - Fields to update
+   */
+  update(domain, id, record) {
+    return request('PUT', `/v1/dns/records/${id}`, {
+      domain,
+      type: record.type,
+      name: record.host || record.name,
+      value: record.value,
+      ttl: record.ttl,
+      priority: record.priority
+    });
+  },
+
+  /**
+   * Delete a DNS record
+   * @param {string} domain
+   * @param {string} id - Record ID
+   */
+  delete(domain, id) {
+    return request('DELETE', `/v1/dns/records/${id}`);
+  }
+};
+
+// ─── Nameservers ─────────────────────────────────────────────────────────────
+
+const nameservers = {
+  set(domain, ns) {
+    return request('PUT', `/v1/domains/${domain}/nameservers`, { nameservers: ns });
+  },
+  list(domain) {
+    return request('GET', `/v1/domains/${domain}/nameservers`).then(d => d.nameservers || []);
+  },
+  register(domain, host, ips) {
+    return request('POST', `/v1/domains/${domain}/nameservers/registered`, { host, ips: Array.isArray(ips) ? ips : [ips] });
+  },
+  modify(domain, host, ips) {
+    return request('PUT', `/v1/domains/${domain}/nameservers/registered/${encodeURIComponent(host)}`, { ips: Array.isArray(ips) ? ips : [ips] });
+  },
+  unregister(domain, host) {
+    return request('DELETE', `/v1/domains/${domain}/nameservers/registered/${encodeURIComponent(host)}`);
+  },
+  listRegistered(domain) {
+    return request('GET', `/v1/domains/${domain}/nameservers/registered`).then(d => d.hosts || []);
+  }
+};
+
+// ─── Contacts ─────────────────────────────────────────────────────────────────
+
+const contacts = {
+  list() {
+    return request('GET', '/v1/contacts').then(d => d.contacts || []);
+  },
+  add(contact) {
+    return request('POST', '/v1/contacts', contact);
+  },
+  update(id, contact) {
+    return request('PUT', `/v1/contacts/${id}`, contact);
+  },
+  delete(id) {
+    return request('DELETE', `/v1/contacts/${id}`);
+  },
+  associate(id, domain) {
+    return request('POST', `/v1/domains/${domain}/contact`, { contact_id: id });
+  }
+};
+
+// ─── User Account ─────────────────────────────────────────────────────────────
+
+const account = {
+  me() {
+    return request('GET', '/v1/users/me');
+  },
+  preferences(prefs) {
+    return request('PUT', '/v1/users/me/preferences', prefs);
+  },
+  audit(page = 1, limit = 50) {
+    return request('GET', `/v1/users/me/audit?page=${page}&limit=${limit}`);
+  },
+  balance() {
+    return request('GET', '/v1/account/balance');
+  },
+  addFunds(amount, paymentId) {
+    return request('POST', '/v1/account/funds', { amount, payment_id: paymentId });
+  },
+  listPaymentMethods() {
+    return request('GET', '/v1/account/payment-methods').then(d => d.payment_methods || []);
+  },
+  rotateKey() {
+    return request('POST', '/v1/auth/rotate-key');
+  },
+  allowlist: {
+    list() { return request('GET', '/v1/auth/allowlist'); },
+    add(ip) { return request('POST', '/v1/auth/allowlist', { ip }); },
+    remove(ip) { return request('DELETE', `/v1/auth/allowlist/${encodeURIComponent(ip)}`); }
+  }
+};
+
+// ─── High-level Convenience Methods ──────────────────────────────────────────
+
+/**
+ * Search + buy in one flow (if available)
+ * @param {string} domain
+ * @param {Object} opts
+ */
+async function quickBuy(domain, opts = {}) {
+  const results = await search([domain]);
+  const result = results.find(r => r.fqdn === domain);
+  if (!result) throw new Error(`Domain ${domain} not found in search results`);
+  if (!result.available) throw new Error(`Domain ${domain} is not available`);
+  return buy(domain, { autoRenew: true, privacy: true, ...opts });
+}
+
+// Hosting provider DNS templates
+const HOSTING_TEMPLATES = {
+  vercel: { ips: ['76.76.21.21'], cname: 'cname.vercel-dns.com' },
+  netlify: { ips: ['75.2.60.5', '99.83.190.102'], cname: 'apex-loadbalancer.netlify.com' },
+  cloudflare: { ips: ['192.0.2.1'], cname: null, note: 'Point @ A record to your Cloudflare assigned IP, then proxy via CF dashboard' },
+  railway: { ips: [], cname: 'proxy.railway.app' },
+  render: { ips: ['216.24.57.1'], cname: 'oregon-render.global.ssl.fastly.net' },
+  'github-pages': { ips: ['185.199.108.153', '185.199.109.153', '185.199.110.153', '185.199.111.153'], cname: null, note: 'Add CNAME for www pointing to your-username.github.io' }
+};
+
+/**
+ * Set up web DNS records for a domain (A + CNAME for www)
+ * @param {string} domain
+ * @param {string} ipOrProvider - IP address or hosting provider name (vercel, netlify, cloudflare, railway, render)
+ */
+async function setupWeb(domain, ipOrProvider) {
+  const template = typeof ipOrProvider === 'string' ? HOSTING_TEMPLATES[ipOrProvider.toLowerCase()] : null;
+  const added = [];
+
+  if (template) {
+    // Use hosting provider template
+    for (const ip of (template.ips || [])) {
+      added.push(await records.add(domain, { type: 'A', host: '@', value: ip, ttl: 300 }));
+    }
+    if (template.cname) {
+      added.push(await records.add(domain, { type: 'CNAME', host: 'www', value: template.cname, ttl: 300 }));
+    }
+    return { message: `Web DNS configured for ${domain} (${ipOrProvider})`, records: added, note: template.note };
+  } else {
+    // Use raw IP
+    const ip = ipOrProvider;
+    if (!ip) throw new Error('IP address or hosting provider name required');
+    added.push(await records.add(domain, { type: 'A', host: '@', value: ip, ttl: 300 }));
+    added.push(await records.add(domain, { type: 'CNAME', host: 'www', value: domain, ttl: 300 }));
+    return { message: `Web DNS configured for ${domain}`, records: added };
+  }
+}
+
+// Email provider DNS templates
+const EMAIL_TEMPLATES = {
+  gmail: {
+    mx: [
+      { priority: 1, value: 'aspmx.l.google.com' },
+      { priority: 5, value: 'alt1.aspmx.l.google.com' },
+      { priority: 5, value: 'alt2.aspmx.l.google.com' },
+      { priority: 10, value: 'alt3.aspmx.l.google.com' },
+      { priority: 10, value: 'alt4.aspmx.l.google.com' }
+    ],
+    spf: 'v=spf1 include:_spf.google.com ~all',
+    dkimNote: 'Add DKIM TXT record from Google Workspace admin after setup'
+  },
+  office365: {
+    mx: [{ priority: 0, value: (domain) => `${domain.replace(/\./g, '-')}.mail.protection.outlook.com` }],
+    spf: 'v=spf1 include:spf.protection.outlook.com ~all',
+    dkimNote: 'Add DKIM CNAME records from Microsoft 365 admin after setup'
+  },
+  // microsoft365 is an alias for office365
+  microsoft365: {
+    mx: [{ priority: 0, value: (domain) => `${domain.replace(/\./g, '-')}.mail.protection.outlook.com` }],
+    spf: 'v=spf1 include:spf.protection.outlook.com ~all',
+    dkimNote: 'Add DKIM CNAME records from Microsoft 365 admin after setup'
+  },
+  zoho: {
+    mx: [
+      { priority: 10, value: 'mx.zoho.com' },
+      { priority: 20, value: 'mx2.zoho.com' },
+      { priority: 50, value: 'mx3.zoho.com' }
+    ],
+    spf: 'v=spf1 include:zoho.com ~all',
+    dkimNote: 'Add DKIM TXT record from Zoho Mail admin after setup'
+  },
+  titan: {
+    mx: [{ priority: 10, value: 'smtp.titan.email' }],
+    spf: 'v=spf1 include:spf.titan.email ~all',
+    dkimNote: 'Add DKIM TXT record from Titan admin after setup'
+  }
+};
+
+/**
+ * Set up email DNS records (MX + SPF + DMARC) for a domain
+ * @param {string} domain
+ * @param {string} provider - Email provider: gmail, office365, zoho, titan
+ */
+async function setupEmail(domain, provider = 'gmail') {
+  if (!domain || typeof domain !== 'string') {
+    throw new Error('domain must be a non-empty string');
+  }
+  const tmpl = EMAIL_TEMPLATES[provider.toLowerCase()];
+  if (!tmpl) {
+    throw new Error(`Unknown email provider: ${provider}. Supported: ${Object.keys(EMAIL_TEMPLATES).join(', ')}`);
+  }
+
+  const added = [];
+
+  // Add MX records
+  for (const mx of tmpl.mx) {
+    const value = typeof mx.value === 'function' ? mx.value(domain) : mx.value;
+    added.push(await records.add(domain, { type: 'MX', host: '@', value, ttl: 300, priority: mx.priority }));
+  }
+
+  // Add SPF TXT record
+  added.push(await records.add(domain, { type: 'TXT', host: '@', value: tmpl.spf, ttl: 300 }));
+
+  // Add DMARC TXT record
+  added.push(await records.add(domain, {
+    type: 'TXT',
+    host: '_dmarc',
+    value: `v=DMARC1; p=none; rua=mailto:dmarc@${domain}`,
+    ttl: 300
+  }));
+
+  return {
+    message: `Email DNS configured for ${domain} (${provider})`,
+    records: added,
+    note: tmpl.dkimNote
+  };
+}
+
+/**
+ * Clone all DNS records from one domain to another
+ * @param {string} source - Source domain FQDN
+ * @param {string} target - Target domain FQDN
+ */
+async function cloneDns(source, target) {
+  const sourceRecords = await records.list(source);
+  if (!sourceRecords.length) {
+    return { cloned: 0, message: `No DNS records found on ${source}` };
+  }
+
+  const results = [];
+  for (const record of sourceRecords) {
+    try {
+      results.push(await records.add(target, {
+        type: record.type,
+        host: record.name || '@',
+        value: record.value,
+        ttl: record.ttl || 300,
+        priority: record.priority
+      }));
+    } catch (e) {
+      // Skip records that fail (e.g. CNAME conflicts)
+      results.push({ error: e.message, record });
+    }
+  }
+
+  return {
+    cloned: results.filter(r => !r.error).length,
+    failed: results.filter(r => r.error).length,
+    message: `Cloned ${results.filter(r => !r.error).length} of ${sourceRecords.length} records from ${source} to ${target}`,
+    results
+  };
+}
+
+/**
+ * Export all DNS records for a domain as JSON
+ * @param {string} domain
+ */
+async function exportRecords(domain) {
+  return records.list(domain);
+}
+
+/**
+ * Import DNS records for a domain from an array
+ * @param {string} domain
+ * @param {Array} recordsArr
+ */
+async function importRecords(domain, recordsArr) {
+  const results = [];
+  for (const record of recordsArr) {
+    results.push(await records.add(domain, record));
+  }
+  return results;
+}
+
+// ─── Domain Lock / Unlock / Privacy / Auto-Renew ─────────────────────────
+
+/**
+ * Lock a domain to prevent unauthorized transfers
+ * @param {string} domain
+ */
+async function lock(domain) {
+  return request('POST', `/v1/domains/${domain}/lock`);
+}
+
+/**
+ * Unlock a domain (e.g. before initiating a transfer)
+ * @param {string} domain
+ */
+async function unlock(domain) {
+  return request('POST', `/v1/domains/${domain}/unlock`);
+}
+
+/**
+ * Toggle WHOIS privacy for a domain
+ * @param {string} domain
+ * @param {boolean} enabled
+ */
+async function privacy(domain, enabled) {
+  return request('POST', `/v1/domains/${domain}/privacy`, { enabled });
+}
+
+/**
+ * Toggle auto-renewal for a domain
+ * @param {string} domain
+ * @param {boolean} enabled
+ */
+async function autoRenew(domain, enabled) {
+  return request('POST', `/v1/domains/${domain}/auto-renew`, { enabled });
+}
+
+async function transfer(domain, authCode, opts = {}) {
+  return request('POST', `/v1/domains/${domain}/transfer`, { auth_code: authCode, years: opts.years || 1 });
+}
+async function transferCheck(domain) {
+  return request('GET', `/v1/domains/${domain}/transfer-check`);
+}
+async function transferStatus(domain) {
+  return request('GET', `/v1/domains/${domain}/transfer-status`);
+}
+async function transferUpdateEpp(domain, auth) {
+  return request('POST', `/v1/domains/${domain}/transfer-update-epp`, { auth });
+}
+async function transferResendEmail(domain) {
+  return request('POST', `/v1/domains/${domain}/transfer-resend`);
+}
+async function transferResubmit(domain) {
+  return request('POST', `/v1/domains/${domain}/transfer-resubmit`);
+}
+async function expiring(days = 30) {
+  const data = await request('GET', `/v1/domains/expiring?days=${days}`);
+  return data.domains || [];
+}
+
+async function authCode(domain) {
+  return request('GET', `/v1/domains/${domain}/auth-code`);
+}
+
+
+// ─── Forwarding ──────────────────────────────────────────────────────────────
+const forwarding = {
+  set(domain, url) {
+    return request('POST', `/v1/domains/${domain}/forward`, { url });
+  },
+  setSub(domain, subdomain, url) {
+    return request('POST', `/v1/domains/${domain}/forward-sub`, { subdomain, url });
+  },
+  deleteSub(domain, subdomain) {
+    return request('DELETE', `/v1/domains/${domain}/forward-sub/${subdomain}`);
+  }
+};
+
+// ─── Email Forwarding ─────────────────────────────────────────────────────
+const email = {
+  list(domain) {
+    return request('GET', `/v1/domains/${domain}/email-fwd`).then(d => d.forwards || []);
+  },
+  forward(domain, fromEmail, toEmail) {
+    return request('POST', `/v1/domains/${domain}/email-fwd`, { from_email: fromEmail, to_email: toEmail });
+  },
+  deleteForward(domain, fromEmail) {
+    return request('DELETE', `/v1/domains/${domain}/email-fwd/${encodeURIComponent(fromEmail)}`);
+  }
+};
+
+
+// ─── Webhooks ────────────────────────────────────────────────────────────────
+const webhooks = {
+  list() {
+    return request('GET', '/v1/webhooks').then(d => d.webhooks || []);
+  },
+  add(url, events, secret) {
+    return request('POST', '/v1/webhooks', { url, events, secret });
+  },
+  delete(id) {
+    return request('DELETE', `/v1/webhooks/${id}`);
+  },
+  update(id, opts) {
+    return request('PUT', `/v1/webhooks/${id}`, opts);
+  },
+  test(id) {
+    return request('POST', `/v1/webhooks/${id}/test`);
+  }
+};
+
+// ─── Portfolio ────────────────────────────────────────────────────────────────
+const portfolio = {
+  list() {
+    return request('GET', '/v1/portfolio').then(d => d.portfolios || []);
+  },
+  create(name) {
+    return request('POST', '/v1/portfolio', { name });
+  },
+  delete(name) {
+    return request('DELETE', `/v1/portfolio/${encodeURIComponent(name)}`);
+  },
+  assign(name, domains) {
+    return request('POST', `/v1/portfolio/${encodeURIComponent(name)}/assign`, { domains: Array.isArray(domains) ? domains : [domains] });
+  }
+};
+
+// ─── Orders ──────────────────────────────────────────────────────────────────
+const orders = {
+  list() {
+    return request('GET', '/v1/orders').then(d => d.orders || []);
+  },
+  details(orderNumber) {
+    return request('GET', `/v1/orders/${encodeURIComponent(orderNumber)}`);
+  }
+};
+
+// ─── DNSSEC ──────────────────────────────────────────────────────────────────
+const dnssec = {
+  list(domain) {
+    return request('GET', `/v1/domains/${domain}/dnssec`).then(d => d.records || []);
+  },
+  add(domain, record) {
+    // Normalize camelCase → snake_case so both styles work
+    const normalized = {
+      key_tag: record.key_tag ?? record.keyTag,
+      algorithm: record.algorithm,
+      digest_type: record.digest_type ?? record.digestType,
+      digest: record.digest
+    };
+    return request('POST', `/v1/domains/${domain}/dnssec`, normalized);
+  },
+  delete(domain, record) {
+    const normalized = {
+      key_tag: record.key_tag ?? record.keyTag,
+      algorithm: record.algorithm,
+      digest_type: record.digest_type ?? record.digestType,
+      digest: record.digest
+    };
+    return request('DELETE', `/v1/domains/${domain}/dnssec`, normalized);
+  }
+};
+
+// ─── WHOIS ────────────────────────────────────────────────────────────────────
+async function whois(domain) {
+  return request('GET', `/v1/domains/${domain}/whois`);
+}
+
+
+// ─── Domain Push & Registrant Verification ────────────────────────────────────
+async function push(domain, toEmail) {
+  return request('POST', `/v1/domains/${domain}/push`, { to_email: toEmail });
+}
+async function verificationStatus() {
+  return request('GET', '/v1/verification/status');
+}
+async function emailVerify(email) {
+  return request('POST', '/v1/verification/email', { email });
+}
+
+module.exports = {
+  // Domain ops
+  search,
+  buy,
+  confirmPurchase,
+  list,
+  info,
+  prices,
+  renew,
+  lock,
+  unlock,
+  privacy,
+  autoRenew,
+  quickBuy,
+  transfer,
+  transferCheck,
+  transferStatus,
+  transferUpdateEpp,
+  transferResendEmail,
+  transferResubmit,
+  buyDrop,
+  authCode,
+  expiring,
+  // DNS records
+  records,
+  // Nameservers
+  nameservers,
+  // Forwarding
+  forwarding,
+  // Email forwarding
+  email,
+  // Webhooks
+  webhooks,
+  // DNSSEC
+  dnssec,
+  // WHOIS
+  whois,
+  // Contacts
+  contacts,
+  // Account
+  account,
+  // Convenience
+  setupWeb,
+  setupEmail,
+  exportRecords,
+  importRecords,
+  cloneDns,
+  // Provider templates (exported for reference)
+  HOSTING_TEMPLATES,
+  EMAIL_TEMPLATES,
+  // Portfolio
+  portfolio,
+  // Orders
+  orders,
+  // Domain push & verification
+  push,
+  verificationStatus,
+  emailVerify,
+  // Errors
+  ...require('./lib/client')
+};