phasmid 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright <2026> <Smiduweorc>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * Phasmid: provider-aware email normalization and canonicalization.
+ *
+ * @example
+ * ```ts
+ * import { normalizeEmail, isSameEmail } from "Phasmid";
+ *
+ * normalizeEmail("John.Doe+newsletter@googlemail.com"); // "johndoe@gmail.com"
+ * isSameEmail("a.b@gmail.com", "ab@gmail.com");          // true
+ * ```
+ */
+export { normalizeEmail, normalizeEmailDetailed, getEmailProvider, isSameEmail, } from "./src/normalize.js";
+export { DEFAULT_PROVIDERS } from "./src/providers.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,GACX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/normalize.js

@@ -0,0 +1,149 @@
+import { DEFAULT_PROVIDERS } from "./providers.js";
+/** Conservative fallback used for domains that match no provider. */
+const CONSERVATIVE_DEFAULT = {
+    lowercaseLocal: false,
+    removeDots: false,
+    subaddressSeparators: [],
+};
+/** A basic domain shape: labels separated by dots, with a final TLD label. */
+const DOMAIN_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i;
+/** Lazily-built registry for the default-only case (the common path). */
+let defaultRegistry = null;
+function buildRegistry(providers) {
+    const map = new Map();
+    for (const provider of providers) {
+        for (const domain of provider.domains) {
+            map.set(domain.toLowerCase(), provider);
+        }
+    }
+    return map;
+}
+function getRegistry(options) {
+    if (!options.providers && !options.replaceDefaultProviders) {
+        return (defaultRegistry ??= buildRegistry(DEFAULT_PROVIDERS));
+    }
+    const base = options.replaceDefaultProviders ? [] : DEFAULT_PROVIDERS;
+    // Later entries override earlier ones, so user providers take precedence.
+    return buildRegistry([...base, ...(options.providers ?? [])]);
+}
+/** Split on the last `@`, the way most parsers treat the local/domain boundary. */
+function splitEmail(email) {
+    const at = email.lastIndexOf("@");
+    if (at <= 0 || at === email.length - 1)
+        return null;
+    return { local: email.slice(0, at), domain: email.slice(at + 1) };
+}
+/** A quoted local part (`"a b"@x.com`) is preserved verbatim. */
+function isQuoted(local) {
+    return local.length >= 2 && local.startsWith("\"") && local.endsWith("\"");
+}
+function stripSubaddress(local, separators) {
+    let cut = -1;
+    let cutLen = 0;
+    for (const sep of separators) {
+        if (!sep)
+            continue;
+        const idx = local.indexOf(sep);
+        // Ignore a separator at index 0; cutting there yields an empty local part.
+        if (idx > 0 && (cut === -1 || idx < cut)) {
+            cut = idx;
+            cutLen = sep.length;
+        }
+    }
+    if (cut === -1)
+        return { local, subaddress: null };
+    return { local: local.slice(0, cut), subaddress: local.slice(cut + cutLen) };
+}
+function isValidLocal(local) {
+    if (local.length === 0)
+        return false;
+    if (isQuoted(local))
+        return true;
+    return !/[\s@]/.test(local);
+}
+/**
+ * Normalize an email address and return the full structured result, including
+ * the matched provider, the stripped sub-address, and a validity flag.
+ *
+ * @throws {TypeError} if `email` is not a string.
+ */
+export function normalizeEmailDetailed(email, options = {}) {
+    if (typeof email !== "string") {
+        throw new TypeError(`Expected email to be a string, received ${typeof email}`);
+    }
+    const lowercaseDomain = options.lowercaseDomain ?? true;
+    const trimmed = email.trim();
+    const parts = splitEmail(trimmed);
+    if (!parts) {
+        return {
+            normalized: trimmed,
+            local: trimmed,
+            domain: "",
+            providerId: null,
+            subaddress: null,
+            valid: false,
+        };
+    }
+    const lookupDomain = parts.domain.toLowerCase();
+    const provider = getRegistry(options).get(lookupDomain) ?? null;
+    const rule = provider ?? options.defaultRule ?? CONSERVATIVE_DEFAULT;
+    let local = parts.local;
+    let subaddress = null;
+    if (!isQuoted(local)) {
+        const stripped = stripSubaddress(local, rule.subaddressSeparators ?? []);
+        local = stripped.local;
+        subaddress = stripped.subaddress;
+        if (rule.removeDots)
+            local = local.replace(/\./g, "");
+        if (rule.lowercaseLocal)
+            local = local.toLowerCase();
+    }
+    let domain = lowercaseDomain ? lookupDomain : parts.domain;
+    if (provider?.canonicalDomain) {
+        domain = lowercaseDomain
+            ? provider.canonicalDomain.toLowerCase()
+            : provider.canonicalDomain;
+    }
+    const valid = isValidLocal(local) && DOMAIN_RE.test(domain);
+    return {
+        normalized: `${local}@${domain}`,
+        local,
+        domain,
+        providerId: provider?.id ?? null,
+        subaddress,
+        valid,
+    };
+}
+/**
+ * Normalize an email address to its canonical form.
+ *
+ * Applies the matching provider's rules (sub-address stripping, dot removal,
+ * case-folding, alias-domain collapsing) and returns the canonical string.
+ * Unknown domains get a conservative treatment: the domain is lowercased and
+ * the local part is left untouched.
+ *
+ * @throws {TypeError} if `email` is not a string.
+ */
+export function normalizeEmail(email, options) {
+    return normalizeEmailDetailed(email, options).normalized;
+}
+/**
+ * Return the id of the provider that handles the given address's domain, or
+ * `null` if no provider matches (or the input is not a valid address).
+ */
+export function getEmailProvider(email, options = {}) {
+    if (typeof email !== "string")
+        return null;
+    const parts = splitEmail(email.trim());
+    if (!parts)
+        return null;
+    return getRegistry(options).get(parts.domain.toLowerCase())?.id ?? null;
+}
+/**
+ * Returns `true` if two addresses normalize to the same canonical address,
+ * i.e. they deliver to the same mailbox under the configured rules.
+ */
+export function isSameEmail(a, b, options) {
+    return normalizeEmail(a, options) === normalizeEmail(b, options);
+}
+//# sourceMappingURL=normalize.js.map

package/dist/src/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAQnD,qEAAqE;AACrE,MAAM,oBAAoB,GAA0B;IACnD,cAAc,EAAE,KAAK;IACrB,UAAU,EAAE,KAAK;IACjB,oBAAoB,EAAE,EAAE;CACxB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,SAAS,GACd,0EAA0E,CAAC;AAE5E,yEAAyE;AACzE,IAAI,eAAe,GAAqC,IAAI,CAAC;AAE7D,SAAS,aAAa,CACrB,SAAkC;IAElC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC5C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAClC,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACvC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,SAAS,WAAW,CAAC,OAAyB;IAC7C,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,uBAAuB,EAAE,CAAC;QAC5D,OAAO,CAAC,eAAe,KAAK,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC;IACtE,0EAA0E;IAC1E,OAAO,aAAa,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,mFAAmF;AACnF,SAAS,UAAU,CAAC,KAAa;IAChC,MAAM,EAAE,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,iEAAiE;AACjE,SAAS,QAAQ,CAAC,KAAa;IAC9B,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,eAAe,CACvB,KAAa,EACb,UAA6B;IAE7B,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,2EAA2E;QAC3E,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;YAC1C,GAAG,GAAG,GAAG,CAAC;YACV,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACrB,CAAC;IACF,CAAC;IACD,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACnD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACrC,KAAa,EACb,UAA4B,EAAE;IAE9B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CAClB,2CAA2C,OAAO,KAAK,EAAE,CACzD,CAAC;IACH,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC;IACxD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAElC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO;YACN,UAAU,EAAE,OAAO;YACnB,KAAK,EAAE,OAAO;YACd,MAAM,EAAE,EAAE;YACV,UAAU,EAAE,IAAI;YAChB,UAAU,EAAE,IAAI;YAChB,KAAK,EAAE,KAAK;SACZ,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IAChD,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC;IAChE,MAAM,IAAI,GAAG,QAAQ,IAAI,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAErE,IAAI,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACxB,IAAI,UAAU,GAAkB,IAAI,CAAC;IAErC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;QACzE,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QACvB,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;QACjC,IAAI,IAAI,CAAC,UAAU;YAAE,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,cAAc;YAAE,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACtD,CAAC;IAED,IAAI,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3D,IAAI,QAAQ,EAAE,eAAe,EAAE,CAAC;QAC/B,MAAM,GAAG,eAAe;YACvB,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,WAAW,EAAE;YACxC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC;IAC7B,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAE5D,OAAO;QACN,UAAU,EAAE,GAAG,KAAK,IAAI,MAAM,EAAE;QAChC,KAAK;QACL,MAAM;QACN,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,IAAI;QAChC,UAAU;QACV,KAAK;KACL,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC7B,KAAa,EACb,OAA0B;IAE1B,OAAO,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC/B,KAAa,EACb,UAA4B,EAAE;IAE9B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAC1B,CAAS,EACT,CAAS,EACT,OAA0B;IAE1B,OAAO,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC"}

package/dist/src/providers.js

@@ -0,0 +1,182 @@
+/**
+ * Built-in provider rules.
+ *
+ * These encode the well-documented, widely-relied-upon behaviors of major mail
+ * providers. They are deliberately conservative: domains are only collapsed
+ * where aliases truly deliver to the same mailbox (Gmail), and local parts are
+ * only lowercased for providers known to be case-insensitive.
+ *
+ * Sources cross-checked while compiling this list:
+ *   - Wikipedia, "Email address" (sub-addressing section).
+ *   - aaronbassett's "Email sub addressing for different providers" gist.
+ *   - validator.js `normalizeEmail` provider conventions.
+ *   - Fastmail / Microsoft Learn / Proton provider documentation.
+ *
+ * Consumers can extend or override any of these via
+ * {@link NormalizeOptions.providers}.
+ */
+export const DEFAULT_PROVIDERS = Object.freeze([
+    {
+        // Gmail ignores dots, supports `+` tagging, and treats googlemail.com as
+        // an alias of gmail.com.
+        id: "gmail",
+        domains: ["gmail.com", "googlemail.com"],
+        canonicalDomain: "gmail.com",
+        lowercaseLocal: true,
+        removeDots: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        // Microsoft consumer mail (Outlook.com / Hotmail / Live / MSN). Dots are
+        // significant; `+` tagging is supported. The domains are distinct
+        // mailboxes, so they are not collapsed.
+        id: "microsoft",
+        domains: [
+            "outlook.com",
+            "outlook.com.au",
+            "outlook.co.uk",
+            "outlook.fr",
+            "outlook.de",
+            "outlook.es",
+            "outlook.it",
+            "outlook.jp",
+            "hotmail.com",
+            "hotmail.co.uk",
+            "hotmail.com.au",
+            "hotmail.fr",
+            "hotmail.de",
+            "hotmail.it",
+            "hotmail.es",
+            "hotmail.ca",
+            "live.com",
+            "live.com.au",
+            "live.co.uk",
+            "live.fr",
+            "live.de",
+            "live.ca",
+            "msn.com",
+            "windowslive.com",
+            "passport.com",
+        ],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        // Yahoo historically uses a hyphen as its sub-address separator (its
+        // "disposable addresses" feature), not `+`.
+        id: "yahoo",
+        domains: [
+            "yahoo.com",
+            "yahoo.co.uk",
+            "yahoo.ie",
+            "yahoo.fr",
+            "yahoo.de",
+            "yahoo.es",
+            "yahoo.it",
+            "yahoo.ca",
+            "yahoo.in",
+            "yahoo.com.au",
+            "yahoo.com.br",
+            "yahoo.com.mx",
+            "yahoo.com.ar",
+            "yahoo.co.jp",
+            "ymail.com",
+            "rocketmail.com",
+        ],
+        lowercaseLocal: true,
+        subaddressSeparators: ["-"],
+    },
+    {
+        // Apple iCloud. me.com and mac.com forward to the same Apple ID, but we
+        // keep them distinct by default to avoid surprising collapses.
+        id: "icloud",
+        domains: ["icloud.com", "me.com", "mac.com"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        // Fastmail also supports subdomain addressing
+        // (user+tag@fastmail.com == tag@user.fastmail.com), which is not
+        // resolved here because it depends on the account's domain layout.
+        id: "fastmail",
+        domains: ["fastmail.com", "fastmail.fm"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "proton",
+        domains: ["protonmail.com", "protonmail.ch", "proton.me", "pm.me"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "yandex",
+        domains: [
+            "yandex.com",
+            "yandex.ru",
+            "ya.ru",
+            "yandex.by",
+            "yandex.kz",
+            "yandex.ua",
+        ],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "zoho",
+        domains: ["zoho.com", "zohomail.com", "zoho.eu"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "mailfence",
+        domains: ["mailfence.com"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "runbox",
+        domains: ["runbox.com"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        // Pobox is part of the Fastmail family.
+        id: "pobox",
+        domains: ["pobox.com"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "tutanota",
+        domains: [
+            "tutanota.com",
+            "tutanota.de",
+            "tutamail.com",
+            "tuta.com",
+            "tuta.io",
+            "keemail.me",
+        ],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "posteo",
+        domains: ["posteo.de", "posteo.net"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        id: "mailbox",
+        domains: ["mailbox.org"],
+        lowercaseLocal: true,
+        subaddressSeparators: ["+"],
+    },
+    {
+        // AOL is case-insensitive but does not support `+` tagging.
+        id: "aol",
+        domains: ["aol.com", "aim.com"],
+        lowercaseLocal: true,
+    },
+]);
+//# sourceMappingURL=providers.js.map

package/dist/src/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Phasmid: provider-aware email normalization and canonicalization.
+ *
+ * @example
+ * ```ts
+ * import { normalizeEmail, isSameEmail } from "Phasmid";
+ *
+ * normalizeEmail("John.Doe+newsletter@googlemail.com"); // "johndoe@gmail.com"
+ * isSameEmail("a.b@gmail.com", "ab@gmail.com");          // true
+ * ```
+ */
+export { normalizeEmail, normalizeEmailDetailed, getEmailProvider, isSameEmail, } from "./src/normalize.js";
+export { DEFAULT_PROVIDERS } from "./src/providers.js";
+export type { ProviderRule, DefaultRule, LocalPartRules, NormalizeOptions, NormalizedEmail, } from "./src/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,GACX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,YAAY,EACX,YAAY,EACZ,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,eAAe,GACf,MAAM,gBAAgB,CAAC"}

package/dist/types/src/normalize.d.ts

@@ -0,0 +1,30 @@
+import type { NormalizeOptions, NormalizedEmail } from "./types.js";
+/**
+ * Normalize an email address and return the full structured result, including
+ * the matched provider, the stripped sub-address, and a validity flag.
+ *
+ * @throws {TypeError} if `email` is not a string.
+ */
+export declare function normalizeEmailDetailed(email: string, options?: NormalizeOptions): NormalizedEmail;
+/**
+ * Normalize an email address to its canonical form.
+ *
+ * Applies the matching provider's rules (sub-address stripping, dot removal,
+ * case-folding, alias-domain collapsing) and returns the canonical string.
+ * Unknown domains get a conservative treatment: the domain is lowercased and
+ * the local part is left untouched.
+ *
+ * @throws {TypeError} if `email` is not a string.
+ */
+export declare function normalizeEmail(email: string, options?: NormalizeOptions): string;
+/**
+ * Return the id of the provider that handles the given address's domain, or
+ * `null` if no provider matches (or the input is not a valid address).
+ */
+export declare function getEmailProvider(email: string, options?: NormalizeOptions): string | null;
+/**
+ * Returns `true` if two addresses normalize to the same canonical address,
+ * i.e. they deliver to the same mailbox under the configured rules.
+ */
+export declare function isSameEmail(a: string, b: string, options?: NormalizeOptions): boolean;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/types/src/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEX,gBAAgB,EAChB,eAAe,EAEf,MAAM,YAAY,CAAC;AA0EpB;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC5B,eAAe,CAsDjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACxB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC5B,MAAM,GAAG,IAAI,CAKf;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAET"}

package/dist/types/src/providers.d.ts

@@ -0,0 +1,20 @@
+import type { ProviderRule } from "./types.js";
+/**
+ * Built-in provider rules.
+ *
+ * These encode the well-documented, widely-relied-upon behaviors of major mail
+ * providers. They are deliberately conservative: domains are only collapsed
+ * where aliases truly deliver to the same mailbox (Gmail), and local parts are
+ * only lowercased for providers known to be case-insensitive.
+ *
+ * Sources cross-checked while compiling this list:
+ *   - Wikipedia, "Email address" (sub-addressing section).
+ *   - aaronbassett's "Email sub addressing for different providers" gist.
+ *   - validator.js `normalizeEmail` provider conventions.
+ *   - Fastmail / Microsoft Learn / Proton provider documentation.
+ *
+ * Consumers can extend or override any of these via
+ * {@link NormalizeOptions.providers}.
+ */
+export declare const DEFAULT_PROVIDERS: readonly ProviderRule[];
+//# sourceMappingURL=providers.d.ts.map

package/dist/types/src/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,YAAY,EAmKnD,CAAC"}

package/dist/types/src/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The set of transformations that can be applied to the local part of an
+ * address. Both {@link ProviderRule} and {@link DefaultRule} share these
+ * fields so the engine can treat a matched provider and a fallback rule
+ * uniformly.
+ */
+export interface LocalPartRules {
+    /**
+     * Lowercase the local part. Most consumer providers treat the local part
+     * case-insensitively, so this is enabled for the built-in providers. The
+     * email spec (RFC 5321) technically allows case-sensitive local parts, so
+     * it is left disabled for unknown domains by default.
+     */
+    lowercaseLocal?: boolean;
+    /**
+     * Remove all dots (`.`) from the local part. This is Gmail's behavior:
+     * `john.doe@gmail.com` and `johndoe@gmail.com` are the same mailbox.
+     */
+    removeDots?: boolean;
+    /**
+     * Characters that begin a "sub-address" (also called plus-addressing or
+     * tagging). Everything from the first occurrence of any separator to the
+     * end of the local part is stripped. Gmail/Outlook/etc. use `"+"`; Yahoo
+     * historically uses `"-"`.
+     *
+     * A separator at index 0 is ignored, because stripping it would leave an
+     * empty local part.
+     */
+    subaddressSeparators?: string[];
+}
+/**
+ * A rule describing how a specific email provider's addresses should be
+ * canonicalized.
+ */
+export interface ProviderRule extends LocalPartRules {
+    /** Stable identifier for the provider, e.g. `"gmail"`. */
+    id: string;
+    /**
+     * The domains this rule applies to. Matched case-insensitively. The first
+     * provider registered for a domain wins, and user-supplied providers
+     * override the built-ins.
+     */
+    domains: string[];
+    /**
+     * Collapse every matched domain to this single canonical domain. Used for
+     * provider aliases that deliver to the same mailbox, e.g. `googlemail.com`
+     * -> `gmail.com`.
+     */
+    canonicalDomain?: string;
+}
+/**
+ * The fallback rule applied to domains that do not match any provider. It is
+ * the same as a {@link ProviderRule} minus the identity fields, and it cannot
+ * rewrite the domain.
+ */
+export type DefaultRule = LocalPartRules;
+/**
+ * Options accepted by the normalization functions.
+ */
+export interface NormalizeOptions {
+    /**
+     * Additional provider rules, or overrides for the built-in providers.
+     * Matched by domain; entries here take precedence over the built-ins.
+     */
+    providers?: ProviderRule[];
+    /**
+     * Ignore the built-in provider list entirely and use only the providers
+     * supplied in {@link NormalizeOptions.providers}. Defaults to `false`.
+     */
+    replaceDefaultProviders?: boolean;
+    /**
+     * Rule applied to domains that match no provider. Defaults to a
+     * conservative rule that only lowercases the domain and leaves the local
+     * part untouched.
+     */
+    defaultRule?: DefaultRule;
+    /**
+     * Lowercase the domain. Domains are case-insensitive per RFC 1035, so this
+     * defaults to `true`. Disabling it is rarely useful but available.
+     */
+    lowercaseDomain?: boolean;
+}
+/**
+ * The structured result of normalizing an address.
+ */
+export interface NormalizedEmail {
+    /** The fully normalized address, `${local}@${domain}`. */
+    normalized: string;
+    /** The normalized local part (before the `@`). */
+    local: string;
+    /** The normalized domain (after the `@`). */
+    domain: string;
+    /** The id of the provider that matched, or `null` if none did. */
+    providerId: string | null;
+    /** The sub-address ("tag") that was stripped, or `null` if there was none. */
+    subaddress: string | null;
+    /** Whether the input looks like a syntactically valid address. */
+    valid: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IACnD,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IAEX;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAE3B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAC;CACf"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "phasmid",
-	"version": "0.0.1",
+	"version": "1.0.0",
 	"description": "TypeScript library for data transformation and normalization.",
 	"type": "module",
 	"main": "dist/index.js",