mailintel 0.2.0

package/dist/index.js

@@ -0,0 +1,569 @@
+// src/dns.ts
+var RESOLVERS = {
+  cloudflare: "https://cloudflare-dns.com/dns-query",
+  google: "https://dns.google/resolve"
+};
+async function lookupMx(domain, options = {}) {
+  const resolver = options.resolver ?? "cloudflare";
+  const timeout = options.timeout ?? 5e3;
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const url = `${RESOLVERS[resolver]}?name=${encodeURIComponent(domain)}&type=MX`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetchFn(url, {
+      headers: { Accept: "application/dns-json" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return { records: [], raw: {} };
+    }
+    const data = await response.json();
+    const records = (data.Answer ?? []).filter((r) => r.type === 15).map((r) => {
+      const parts = r.data.split(" ");
+      return {
+        priority: parseInt(parts[0], 10),
+        exchange: parts[1]?.replace(/\.$/, "") ?? ""
+      };
+    }).sort((a, b) => a.priority - b.priority);
+    return { records, raw: data };
+  } catch {
+    return { records: [], raw: {} };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/ispdb.ts
+var ISPDB_URL = "https://autoconfig.thunderbird.net/v1.1";
+async function lookupIspdb(domain, options = {}) {
+  const timeout = options.timeout ?? 5e3;
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const url = `${ISPDB_URL}/${encodeURIComponent(domain)}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetchFn(url, { signal: controller.signal });
+    if (!response.ok) {
+      return { connection: null, raw: null };
+    }
+    const xml = await response.text();
+    const connection = parseIspdbXml(xml);
+    return { connection, raw: xml };
+  } catch {
+    return { connection: null, raw: null };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function parseIspdbXml(xml) {
+  const imapMatch = xml.match(/<incomingServer type="imap">([\s\S]*?)<\/incomingServer>/);
+  const smtpMatch = xml.match(/<outgoingServer type="smtp">([\s\S]*?)<\/outgoingServer>/);
+  if (!imapMatch || !smtpMatch) return null;
+  const imapBlock = imapMatch[1];
+  const smtpBlock = smtpMatch[1];
+  const imapHost = imapBlock.match(/<hostname>(.*?)<\/hostname>/)?.[1];
+  const imapPort = imapBlock.match(/<port>(.*?)<\/port>/)?.[1];
+  const imapSocket = imapBlock.match(/<socketType>(.*?)<\/socketType>/)?.[1];
+  const smtpHost = smtpBlock.match(/<hostname>(.*?)<\/hostname>/)?.[1];
+  const smtpPort = smtpBlock.match(/<port>(.*?)<\/port>/)?.[1];
+  const smtpSocket = smtpBlock.match(/<socketType>(.*?)<\/socketType>/)?.[1];
+  const username = xml.match(/<username>(.*?)<\/username>/)?.[1] ?? "%EMAILADDRESS%";
+  if (!imapHost || !imapPort || !smtpHost || !smtpPort) return null;
+  return {
+    imap: {
+      host: imapHost,
+      port: parseInt(imapPort, 10),
+      secure: imapSocket === "SSL"
+    },
+    smtp: {
+      host: smtpHost,
+      port: parseInt(smtpPort, 10),
+      secure: smtpSocket === "SSL" || smtpSocket === "STARTTLS"
+    },
+    username
+  };
+}
+
+// src/data/domains.ts
+var KNOWN_DOMAINS = {
+  // Google
+  "gmail.com": "google",
+  "googlemail.com": "google",
+  // Microsoft
+  "outlook.com": "microsoft",
+  "hotmail.com": "microsoft",
+  "live.com": "microsoft",
+  "msn.com": "microsoft",
+  "hotmail.co.uk": "microsoft",
+  "hotmail.fr": "microsoft",
+  "outlook.co.uk": "microsoft",
+  // Yahoo
+  "yahoo.com": "yahoo",
+  "yahoo.co.uk": "yahoo",
+  "yahoo.fr": "yahoo",
+  "yahoo.de": "yahoo",
+  "yahoo.co.jp": "yahoo",
+  "ymail.com": "yahoo",
+  "rocketmail.com": "yahoo",
+  // Zoho
+  "zoho.com": "zoho",
+  "zohomail.com": "zoho",
+  "zoho.eu": "zoho",
+  "zoho.in": "zoho",
+  "zoho.com.au": "zoho",
+  "zoho.jp": "zoho",
+  // iCloud
+  "icloud.com": "icloud",
+  "me.com": "icloud",
+  "mac.com": "icloud",
+  // Fastmail
+  "fastmail.com": "fastmail",
+  "fastmail.fm": "fastmail",
+  // Proton
+  "protonmail.com": "protonmail",
+  "proton.me": "protonmail",
+  "pm.me": "protonmail",
+  // Others
+  "aol.com": "aol",
+  "yandex.com": "yandex",
+  "yandex.ru": "yandex",
+  "ya.ru": "yandex",
+  "mail.ru": "mailru",
+  "gmx.com": "gmx",
+  "gmx.de": "gmx",
+  "gmx.net": "gmx",
+  "web.de": "webde",
+  "tutanota.com": "tutanota",
+  "tuta.io": "tutanota",
+  "hey.com": "hey",
+  "mail.com": "mailcom"
+};
+
+// src/data/mx.ts
+var KNOWN_MX = {
+  // Google
+  "google.com": "google",
+  "googlemail.com": "google",
+  // Microsoft
+  "outlook.com": "microsoft",
+  "microsoft.com": "microsoft",
+  "pphosted.com": "microsoft",
+  // Zoho
+  "zoho.com": "zoho",
+  "zoho.eu": "zoho",
+  "zoho.in": "zoho",
+  "zoho.com.au": "zoho",
+  "zoho.jp": "zoho",
+  // Yahoo
+  "yahoodns.net": "yahoo",
+  // Apple
+  "icloud.com": "icloud",
+  "apple.com": "icloud",
+  // Hosting providers
+  "secureserver.net": "godaddy",
+  "titan.email": "titan",
+  "hostinger.com": "hostinger",
+  "ovh.net": "ovh",
+  "ionos.com": "ionos",
+  "emailsrvr.com": "rackspace",
+  "dreamhost.com": "dreamhost",
+  "awsapps.com": "amazon_workmail",
+  // Email-focused providers
+  "fastmail.com": "fastmail",
+  "protonmail.ch": "protonmail",
+  "yandex.net": "yandex",
+  "yandex.ru": "yandex",
+  "migadu.com": "migadu",
+  "improvmx.com": "improvmx",
+  "forwardemail.net": "forwardemail",
+  // Sending-only (no IMAP)
+  "mailgun.org": "mailgun",
+  "sendgrid.net": "sendgrid"
+};
+
+// src/data/providers.ts
+var KNOWN_PROVIDERS = {
+  google: {
+    imap: { host: "imap.gmail.com", port: 993, secure: true },
+    smtp: { host: "smtp.gmail.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  microsoft: {
+    imap: { host: "outlook.office365.com", port: 993, secure: true },
+    smtp: { host: "smtp-mail.outlook.com", port: 587, secure: false },
+    username: "%EMAILADDRESS%"
+  },
+  zoho: {
+    imap: { host: "imappro.zoho.com", port: 993, secure: true },
+    smtp: { host: "smtppro.zoho.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  yahoo: {
+    imap: { host: "imap.mail.yahoo.com", port: 993, secure: true },
+    smtp: { host: "smtp.mail.yahoo.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  icloud: {
+    imap: { host: "imap.mail.me.com", port: 993, secure: true },
+    smtp: { host: "smtp.mail.me.com", port: 587, secure: false },
+    username: "%EMAILADDRESS%"
+  },
+  fastmail: {
+    imap: { host: "imap.fastmail.com", port: 993, secure: true },
+    smtp: { host: "smtp.fastmail.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  protonmail: {
+    imap: { host: "127.0.0.1", port: 1143, secure: false },
+    smtp: { host: "127.0.0.1", port: 1025, secure: false },
+    username: "%EMAILADDRESS%"
+  },
+  godaddy: {
+    imap: { host: "imap.secureserver.net", port: 993, secure: true },
+    smtp: { host: "smtpout.secureserver.net", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  titan: {
+    imap: { host: "imap.titan.email", port: 993, secure: true },
+    smtp: { host: "smtp.titan.email", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  ovh: {
+    imap: { host: "ssl0.ovh.net", port: 993, secure: true },
+    smtp: { host: "ssl0.ovh.net", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  ionos: {
+    imap: { host: "imap.ionos.com", port: 993, secure: true },
+    smtp: { host: "smtp.ionos.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  hostinger: {
+    imap: { host: "imap.hostinger.com", port: 993, secure: true },
+    smtp: { host: "smtp.hostinger.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  yandex: {
+    imap: { host: "imap.yandex.com", port: 993, secure: true },
+    smtp: { host: "smtp.yandex.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  aol: {
+    imap: { host: "imap.aol.com", port: 993, secure: true },
+    smtp: { host: "smtp.aol.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  rackspace: {
+    imap: { host: "secure.emailsrvr.com", port: 993, secure: true },
+    smtp: { host: "secure.emailsrvr.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  },
+  dreamhost: {
+    imap: { host: "imap.dreamhost.com", port: 993, secure: true },
+    smtp: { host: "smtp.dreamhost.com", port: 465, secure: true },
+    username: "%EMAILADDRESS%"
+  }
+};
+var REGIONAL_PROVIDERS = {
+  zoho: {
+    "zoho.eu": { imapHost: "imappro.zoho.eu", smtpHost: "smtppro.zoho.eu" },
+    "zoho.in": { imapHost: "imappro.zoho.in", smtpHost: "smtppro.zoho.in" },
+    "zoho.com.au": { imapHost: "imappro.zoho.com.au", smtpHost: "smtppro.zoho.com.au" },
+    "zoho.jp": { imapHost: "imappro.zoho.jp", smtpHost: "smtppro.zoho.jp" }
+  }
+};
+
+// src/data/free.ts
+var FREE_DOMAINS = /* @__PURE__ */ new Set([
+  "gmail.com",
+  "googlemail.com",
+  "outlook.com",
+  "hotmail.com",
+  "live.com",
+  "msn.com",
+  "hotmail.co.uk",
+  "hotmail.fr",
+  "yahoo.com",
+  "yahoo.co.uk",
+  "yahoo.fr",
+  "yahoo.de",
+  "ymail.com",
+  "icloud.com",
+  "me.com",
+  "mac.com",
+  "protonmail.com",
+  "proton.me",
+  "pm.me",
+  "aol.com",
+  "yandex.com",
+  "yandex.ru",
+  "ya.ru",
+  "mail.ru",
+  "gmx.com",
+  "gmx.de",
+  "gmx.net",
+  "web.de",
+  "zoho.com",
+  "tutanota.com",
+  "tuta.io",
+  "mail.com"
+]);
+
+// src/mailintel.ts
+function resolveUsername(template, email, domain) {
+  return template.replace("%EMAILADDRESS%", email).replace("%EMAILLOCALPART%", email.split("@")[0] ?? "").replace("%EMAILDOMAIN%", domain);
+}
+function resolveConnection(raw, email, domain) {
+  return {
+    imap: raw.imap,
+    smtp: raw.smtp,
+    username: email ? resolveUsername(raw.username, email, domain) : raw.username,
+    usernameTemplate: raw.username
+  };
+}
+async function mailintelCore(input, options, cache, cacheTtl) {
+  const atIndex = input.lastIndexOf("@");
+  const isDomainOnly = atIndex === -1;
+  const email = isDomainOnly ? "" : input;
+  const domain = isDomainOnly ? input.toLowerCase() : input.slice(atIndex + 1).toLowerCase();
+  if (!domain) {
+    return emptyResult(email, "");
+  }
+  if (cache) {
+    const cached = cache.get(domain);
+    if (cached) {
+      return { ...cached, email };
+    }
+  }
+  if (options.providers?.[domain]) {
+    const override = options.providers[domain];
+    const result2 = {
+      email,
+      domain,
+      provider: override.provider,
+      mx: null,
+      type: FREE_DOMAINS.has(domain) ? "free" : "business",
+      isFree: FREE_DOMAINS.has(domain),
+      hasMx: false,
+      connection: resolveConnection(
+        { imap: override.imap, smtp: override.smtp, username: override.username ?? "%EMAILADDRESS%" },
+        email,
+        domain
+      ),
+      confidence: "high",
+      source: "override",
+      raw: { mx: null, dns: null, ispdb: null }
+    };
+    cache?.set(domain, result2, cacheTtl);
+    return result2;
+  }
+  const knownProvider = KNOWN_DOMAINS[domain];
+  if (knownProvider) {
+    const connection2 = KNOWN_PROVIDERS[knownProvider] ?? null;
+    const result2 = {
+      email,
+      domain,
+      provider: knownProvider,
+      mx: null,
+      type: FREE_DOMAINS.has(domain) ? "free" : "business",
+      isFree: FREE_DOMAINS.has(domain),
+      hasMx: false,
+      connection: connection2 ? resolveConnection(connection2, email, domain) : null,
+      confidence: "high",
+      source: "known-domain",
+      raw: { mx: null, dns: null, ispdb: null }
+    };
+    cache?.set(domain, result2, cacheTtl);
+    return result2;
+  }
+  if (options.mxLookup === false) {
+    const result2 = emptyResult(email, domain);
+    cache?.set(domain, result2, cacheTtl);
+    return result2;
+  }
+  const resolver = options.mxLookup === "google" ? "google" : "cloudflare";
+  const { records: mxRecords, raw: dnsRaw } = await lookupMx(domain, {
+    resolver,
+    timeout: options.timeout,
+    fetch: options.fetch
+  });
+  if (mxRecords.length === 0) {
+    const result2 = {
+      email,
+      domain,
+      provider: null,
+      mx: null,
+      type: "unknown",
+      isFree: false,
+      hasMx: false,
+      connection: null,
+      confidence: "low",
+      source: null,
+      raw: { mx: [], dns: dnsRaw, ispdb: null }
+    };
+    cache?.set(domain, result2, cacheTtl);
+    return result2;
+  }
+  const primaryMx = mxRecords[0].exchange;
+  if (options.mxOverrides) {
+    for (const [suffix, override] of Object.entries(options.mxOverrides)) {
+      if (primaryMx === suffix || primaryMx.endsWith("." + suffix)) {
+        const result2 = {
+          email,
+          domain,
+          provider: override.provider,
+          mx: primaryMx,
+          type: FREE_DOMAINS.has(domain) ? "free" : "business",
+          isFree: FREE_DOMAINS.has(domain),
+          hasMx: true,
+          connection: resolveConnection(
+            { imap: override.imap, smtp: override.smtp, username: override.username ?? "%EMAILADDRESS%" },
+            email,
+            domain
+          ),
+          confidence: "high",
+          source: "mx-lookup",
+          raw: { mx: mxRecords, dns: dnsRaw, ispdb: null }
+        };
+        cache?.set(domain, result2, cacheTtl);
+        return result2;
+      }
+    }
+  }
+  let mxProvider = null;
+  let matchedMxSuffix = null;
+  for (const [suffix, provider] of Object.entries(KNOWN_MX)) {
+    if (primaryMx === suffix || primaryMx.endsWith("." + suffix)) {
+      mxProvider = provider;
+      matchedMxSuffix = suffix;
+      break;
+    }
+  }
+  if (mxProvider) {
+    let connection2 = KNOWN_PROVIDERS[mxProvider] ?? null;
+    let ispdbRaw2 = null;
+    let confidence = connection2 ? "high" : "low";
+    if (connection2 && matchedMxSuffix) {
+      const regional = REGIONAL_PROVIDERS[mxProvider];
+      if (regional) {
+        for (const [regionSuffix, regionConfig] of Object.entries(regional)) {
+          if (matchedMxSuffix === regionSuffix || matchedMxSuffix.endsWith("." + regionSuffix)) {
+            connection2 = {
+              ...connection2,
+              imap: { ...connection2.imap, host: regionConfig.imapHost },
+              smtp: { ...connection2.smtp, host: regionConfig.smtpHost }
+            };
+            break;
+          }
+        }
+      }
+    }
+    if (!connection2 && options.ispdb !== false) {
+      const ispdbResult = await lookupIspdb(domain, {
+        timeout: options.timeout,
+        fetch: options.fetch
+      });
+      connection2 = ispdbResult.connection;
+      ispdbRaw2 = ispdbResult.raw;
+      if (connection2) {
+        confidence = "medium";
+      }
+    }
+    const result2 = {
+      email,
+      domain,
+      provider: mxProvider,
+      mx: primaryMx,
+      type: FREE_DOMAINS.has(domain) ? "free" : "business",
+      isFree: FREE_DOMAINS.has(domain),
+      hasMx: true,
+      connection: connection2 ? resolveConnection(connection2, email, domain) : null,
+      confidence,
+      source: "mx-lookup",
+      raw: { mx: mxRecords, dns: dnsRaw, ispdb: ispdbRaw2 }
+    };
+    cache?.set(domain, result2, cacheTtl);
+    return result2;
+  }
+  let connection = null;
+  let ispdbRaw = null;
+  if (options.ispdb !== false) {
+    const ispdbResult = await lookupIspdb(domain, {
+      timeout: options.timeout,
+      fetch: options.fetch
+    });
+    connection = ispdbResult.connection;
+    ispdbRaw = ispdbResult.raw;
+  }
+  const result = {
+    email,
+    domain,
+    provider: null,
+    mx: primaryMx,
+    type: FREE_DOMAINS.has(domain) ? "free" : "business",
+    isFree: FREE_DOMAINS.has(domain),
+    hasMx: true,
+    connection: connection ? resolveConnection(connection, email, domain) : null,
+    confidence: connection ? "medium" : "low",
+    source: connection ? "mx-lookup" : null,
+    raw: { mx: mxRecords, dns: dnsRaw, ispdb: ispdbRaw }
+  };
+  cache?.set(domain, result, cacheTtl);
+  return result;
+}
+function emptyResult(email, domain) {
+  return {
+    email,
+    domain,
+    provider: null,
+    mx: null,
+    type: "unknown",
+    isFree: false,
+    hasMx: false,
+    connection: null,
+    confidence: "low",
+    source: null,
+    raw: { mx: null, dns: null, ispdb: null }
+  };
+}
+
+// src/cache.ts
+var Cache = class {
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expires) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  set(key, value, ttl) {
+    this.store.set(key, { value, expires: Date.now() + ttl });
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/factory.ts
+function createMailintel(options = {}) {
+  const cache = options.cache !== false ? new Cache() : null;
+  const cacheTtl = options.cacheTtl ?? 30 * 60 * 1e3;
+  async function mailintel2(input, callOptions) {
+    const mergedOptions = { ...options, ...callOptions };
+    if (Array.isArray(input)) {
+      return Promise.all(input.map((email) => mailintelCore(email, mergedOptions, cache, cacheTtl)));
+    }
+    return mailintelCore(input, mergedOptions, cache, cacheTtl);
+  }
+  mailintel2.clearCache = () => cache?.clear();
+  return mailintel2;
+}
+
+// src/index.ts
+var mailintel = createMailintel();
+
+export { createMailintel, mailintel, mailintelCore };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "mailintel",
+  "version": "0.2.0",
+  "description": "Email domain intelligence. Takes any email address, resolves the provider, returns IMAP/SMTP connection settings. Supports custom domains via MX lookups.",
+  "author": "Ahmed Atef <ahmed@atef.dev>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "mailintel": "dist/cli.js"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "email",
+    "smtp",
+    "imap",
+    "provider",
+    "mx",
+    "autoconfig",
+    "email-settings",
+    "mail-server",
+    "dns",
+    "mx-lookup"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AhmedAtef07/mailintel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AhmedAtef07/mailintel/issues"
+  },
+  "homepage": "https://github.com/AhmedAtef07/mailintel#readme"
+}