@codelegend/email-validator 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 email-validator contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Bundled disposable-domains.json data:
+Source: https://github.com/disposable-email-domains/disposable-email-domains
+CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+The upstream authors have dedicated this data to the public domain.
+You can copy, modify, distribute and perform the work, even for commercial
+purposes, all without asking permission.
+Details: https://creativecommons.org/publicdomain/zero/1.0/legalcode

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @codelegend/email-validator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency Node.js email validation, bundled disposable-domain blocking, custom domain rules, and Express middleware. CommonJS with TypeScript declarations; Node.js 18 or newer.
+
+## Usage
+
+```sh
+npm install @codelegend/email-validator
+```
+
+```js
+const { createEmailValidator } = require('@codelegend/email-validator');
+
+// Create once and reuse across requests.
+const validator = createEmailValidator({
+  allowedDomains: ['trusted.example.com'],
+  blockedDomains: ['unwanted.example.com'],
+  blockSubdomains: true,
+  useDefaultDomains: true
+});
+
+validator.validateEmail('Alex@example.com');
+// { valid: true, code: 'EMAIL_ACCEPTED', message: 'Email accepted',
+//   email: 'Alex@example.com', domain: 'example.com' }
+
+validator.validateEmail('a@unwanted.example.com');
+// { valid: false, code: 'BLOCKED_DOMAIN', message: 'Email domain is blocked',
+//   email: 'a@unwanted.example.com', domain: 'unwanted.example.com',
+//   matchedDomain: 'unwanted.example.com' }
+
+validator.isValid('hello@example.com'); // true
+validator.validateMany(['hello@example.com', 'bad-address']);
+```
+
+ES modules can import the CommonJS default export:
+
+```js
+import emailValidator from '@codelegend/email-validator';
+const { createEmailValidator } = emailValidator;
+```
+
+Convenience exports `validateEmail(input)` and `isValidEmail(input)` use the default bundled rules. Use a factory instance for custom configuration.
+
+## Rules and results
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `allowedDomains` | `[]` | Exact exceptions overriding custom and bundled blocks |
+| `blockedDomains` | `[]` | Custom domain blocks in addition to bundled disposable domains |
+| `blockSubdomains` | `true` | Blocks apply to descendant domains too |
+| `useDefaultDomains` | `true` | Enable the bundled disposable list |
+
+Rule lists accept arrays or Sets, normalize whitespace, casing, and Unicode domains, and are copied at creation. Invalid configuration throws `TypeError`. Recreate an instance to update its rules. Instances do not share custom configuration.
+
+Syntax is checked first. Exact allowlist matches then override all blocks. Custom blocks are checked next, followed by bundled disposable domains. An allowlist is an exception list, not a restriction to only those domains. Allowing `example.com` does not automatically allow `sub.example.com`. Blocking `example.com` also blocks `sub.example.com` unless `blockSubdomains` is false. Matching respects label boundaries, so `notexample.com` does not match `example.com`.
+
+Every result has `valid`, `code`, and `message`:
+
+| Code | Meaning |
+| --- | --- |
+| `EMAIL_ACCEPTED` | Passed syntax and configured domain rules |
+| `EMAIL_REQUIRED` | Empty or non-string input |
+| `INVALID_EMAIL` | Unsupported or malformed email syntax |
+| `BLOCKED_DOMAIN` | Custom blocking rule matched |
+| `DISPOSABLE_EMAIL` | Bundled disposable rule matched |
+
+Accepted and blocked results include normalized `email` and `domain`; blocked results also include `matchedDomain`. The local part keeps its original casing. Unicode domains become ASCII via Node's IDNA conversion. `validateMany` preserves input order and duplicates; it throws for a non-array argument. Non-string email values produce rejection results rather than throwing.
+
+This is a practical signup policy: ASCII unquoted local parts and dotted domains. It rejects domain literals, numeric final labels, quoted local parts, and Unicode local parts. It does not check public-suffix registration, DNS/MX records, mailbox existence, or deliverability.
+
+## Express
+
+Install Express separately and mount its JSON parser first:
+
+```js
+const express = require('express');
+const { createEmailValidator } = require('@codelegend/email-validator');
+const app = express();
+const validator = createEmailValidator({ blockedDomains: ['unwanted.example.com'] });
+
+app.use(express.json());
+app.post('/signup', validator.middleware, (req, res) => {
+  // req.body.email is normalized. Rejected requests already received HTTP 400.
+  res.json({ email: req.body.email });
+});
+app.listen(3000);
+```
+
+Middleware validates `req.body.email`, returns HTTP 400 with the rejection result, or replaces the email with its normalized value and calls `next()` once. Express is not a package dependency.
+
+## Domain data
+
+Update `disposable-domains.json` directly to maintain the bundled blocklist. No build step is required. The library uses Node's `domainToASCII` for Unicode domain normalization.
+
+## Publishing
+
+1. Run `npm pack --dry-run` to inspect the package files.
+2. Run `npm login`, then `npm publish --access public`.
+
+The package includes only the library, declarations, bundled domain JSON, README, and MIT license. Local credentials are excluded.
+
+## License
+
+Code: MIT. Bundled domain data: CC0 1.0, from [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains). The bundled 9,919 entries were matched against the upstream list on 2026-10-23. See the [upstream license](https://github.com/disposable-email-domains/disposable-email-domains/blob/main/LICENSE.txt).