@mailtester-ninja/client 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailTester Ninja (Unlimited & Limited)
+
+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.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# MailTester Ninja for JavaScript and TypeScript
 
-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.
+Official client for the [MailTester Ninja](https://mailtester.ninja) email verification API. Check in real time whether an email address is valid and deliverable: each address is checked against the recipient's mail server, and nothing is stored. With a paid key, `find` also looks up a person's work email from their name and company domain.
+
+- Zero dependencies, typed, ESM and CommonJS
+- Node.js 18+, Deno, Bun and browsers (CORS is open)
+- Free to try: no signup with `key: "free"`, or a [free API token](https://mailtester.ninja/free-email-verification-api/) for 50 checks a day
+
+```bash
+npm install @mailtester-ninja/client
+```
+
+## Quickstart
+
+```js
+import { MailTester } from '@mailtester-ninja/client';
+
+const mt = new MailTester({ key: process.env.MAILTESTER_KEY }); // falls back to "free"
+
+const result = await mt.verify('info@apple.com');
+console.log(result.code, result.message); // "ok" "Accepted"
+```
+
+CommonJS works too: `const { MailTester } = require('@mailtester-ninja/client');`
+
+## Reading the verdict
+
+Branch on `code`, show `message` to people.
+
+| `code` | Meaning | Typical `message` |
+|--------|---------|-------------------|
+| `ok` | Valid and deliverable | Accepted |
+| `ko` | Invalid, will bounce | Rejected, No MX, Disposable, Limited |
+| `mb` | Uncertain: catch-all domain, or the server could not be probed | Catch-All, MX Error, Timeout, SPAM Block, Greylisted |
+
+A catch-all domain is never reported as valid.
+
+`await mt.isDeliverable(email)` is a shortcut that returns `true` only for `ok`.
+
+## Verify a list
+
+`verifyMany` checks one address at a time and paces the calls for you: 30 seconds apart on the free tier, 1 second with a paid key (override with `delayMs`). Errors are reported per address, the loop keeps going.
+
+```js
+for await (const { email, result, error } of mt.verifyMany(['info@apple.com', 'someone@example.com'])) {
+  if (error) console.log(email, 'no verdict:', error.message);
+  else console.log(email, result.code, result.message);
+}
+```
+
+## Find a work email (paid key)
+
+`find` calls the Finder API: it tests the most common address formats one by one (first.last, flast, first, firstlast, first_last, f.last) and returns the first one the mail server accepts.
+
+```js
+const r = await mt.find('Jean-Pierre', 'De La Tour', 'example.com');
+if (r.found) console.log(r.email);       // an address the mail server just accepted
+else console.log(r.message, r.guess);    // e.g. "Catch-All" and the most common format
+console.log(r.permutations);             // formats tested, each one counted as a verification
+console.log(r.format, r.confidence);     // e.g. "flast" "medium": an initial, a namesake may share it
+```
+
+- Each format tested counts as one verification against your daily limit, even when nothing is found. The search paces itself within the rate of your key.
+- `confidence` tells how sure the address is to belong to this person: `high` when it holds the first and last name, `medium` with an initial, `low` with the first name only. `tested` lists every address checked, with its verdict.
+- On a catch-all domain nothing can be confirmed: `found` is `false` and `guess` holds the most common format.
+- Personal email providers such as gmail.com are not searched (`message` is `Webmail`).
+- A free key is refused with `MailTesterKeyError`; over the rate of your key, `MailTesterRateLimitError` carries `retryAfterSeconds`.
+
+## Errors
+
+An error is never a verdict: do not drop an address because of it.
+
+| Error | When |
+|-------|------|
+| `MailTesterKeyError` | The key is invalid or disabled, or `find` was called with a free key. |
+| `MailTesterRateLimitError` | A limit was reached (HTTP 429). `retryAfterSeconds` is set on the free tier and by `find`. |
+| `MailTesterError` | Any other HTTP or network error (`status` when there is one). |
+
+## Keys and limits
+
+| Key | Daily checks | Pace |
+|-----|--------------|------|
+| `free` | 10 per IP | 1 request every 30 s |
+| Free token `mtf_...` ([get one](https://mailtester.ninja/free-email-verification-api/)) | 50 per token | 1 request every 30 s |
+| Paid key `sub_...` ([plans](https://mailtester.ninja/verify-emails-unlimited/)) | 100,000 to 200,000+ | daily limit / 8640 per 10 s (Pro 11, Ultimate 23) |
+
+Options: `new MailTester({ key, baseUrl, timeoutMs, fetch })`. The key defaults to the `MAILTESTER_KEY` environment variable, then to `free`.
+
+## Links
+
+- [API documentation](https://mailtester.ninja/api/) and [OpenAPI 3.1 specification](https://mailtester.ninja/openapi.json)
+- [Integrations](https://mailtester.ninja/integrations/): n8n, Zapier, Make, Clay, Google Sheets
+- [Code examples](https://github.com/mailtester-ninja/mailtester-api-examples) for other languages
+- [Python client](https://pypi.org/project/mailtester-ninja/)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,186 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  FREE_KEY: () => FREE_KEY,
+  MailTester: () => MailTester,
+  MailTesterError: () => MailTesterError,
+  MailTesterKeyError: () => MailTesterKeyError,
+  MailTesterRateLimitError: () => MailTesterRateLimitError,
+  VERSION: () => VERSION,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var VERSION = "1.1.0";
+var DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
+var FREE_KEY = "free";
+var MailTesterError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "MailTesterError";
+    this.status = status;
+  }
+};
+var MailTesterKeyError = class extends MailTesterError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "MailTesterKeyError";
+  }
+};
+var MailTesterRateLimitError = class extends MailTesterError {
+  retryAfterSeconds;
+  constructor(message, retryAfterSeconds) {
+    super(message, 429);
+    this.name = "MailTesterRateLimitError";
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function envKey() {
+  const g = globalThis;
+  return g.process?.env?.MAILTESTER_KEY || void 0;
+}
+function parseJson(text) {
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === "object" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function retryAfter(message) {
+  const m = /retry in (\d+)\s*s/i.exec(message);
+  return m ? Number(m[1]) : void 0;
+}
+var MailTester = class {
+  key;
+  baseUrl;
+  timeoutMs;
+  fetchImpl;
+  constructor(options = {}) {
+    const opts = typeof options === "string" ? { key: options } : options;
+    this.key = (opts.key ?? envKey() ?? FREE_KEY).trim().replace(/^\{|\}$/g, "");
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? 6e4;
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f) throw new MailTesterError("No fetch implementation available: use Node.js 18 or later, or pass options.fetch");
+    this.fetchImpl = f;
+  }
+  /** True on the free tier (`free` or a free token), limited to one request every 30 seconds. */
+  get isFree() {
+    return this.key === FREE_KEY || this.key.startsWith("mtf_");
+  }
+  async request(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, { headers: { Accept: "application/json" }, signal: controller.signal });
+    } catch (err) {
+      const aborted = err?.name === "AbortError";
+      throw new MailTesterError(aborted ? `Request timed out after ${this.timeoutMs} ms` : `Network error: ${String(err?.message ?? err)}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    return { res, text, body: parseJson(text) };
+  }
+  /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
+  async verify(email) {
+    const { res, text, body } = await this.request(`${this.baseUrl}/ninja?email=${encodeURIComponent(email.trim())}&key=${encodeURIComponent(this.key)}`);
+    const message = typeof body?.message === "string" ? body.message : text.trim();
+    if (res.status === 429) throw new MailTesterRateLimitError(message, retryAfter(message));
+    if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
+    if (!body) throw new MailTesterError("Unexpected response from the API", res.status);
+    if (body.code === "--") throw new MailTesterKeyError(message, res.status);
+    return body;
+  }
+  /**
+   * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+   * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+   * and returns the first address the mail server accepts. Each format tested counts as one verification.
+   * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+   */
+  async find(first, last, domain) {
+    if (this.isFree) {
+      throw new MailTesterKeyError("The Finder API needs a paid key: https://mailtester.ninja/verify-emails-unlimited/", 403);
+    }
+    const qs = new URLSearchParams({ first: first.trim(), last: last.trim(), domain: domain.trim(), key: this.key });
+    const { res, text, body } = await this.request(`${this.baseUrl}/find?${qs}`);
+    const reason = typeof body?.reason === "string" && body.reason ? body.reason : void 0;
+    const message = reason ?? (typeof body?.message === "string" ? body.message : text.trim());
+    if (res.status === 429) {
+      const wait = Number(res.headers.get("retry-after"));
+      throw new MailTesterRateLimitError(message, Number.isFinite(wait) && wait > 0 ? wait : void 0);
+    }
+    if (res.status === 403 && body) throw new MailTesterKeyError(message, 403);
+    if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
+    if (!body) throw new MailTesterError("Unexpected response from the API", res.status);
+    if (body.code === "--") throw new MailTesterKeyError(message, res.status);
+    return body;
+  }
+  /** True only when the address is clearly valid and deliverable (`code` "ok"). */
+  async isDeliverable(email) {
+    return (await this.verify(email)).code === "ok";
+  }
+  /**
+   * Verify a list, one address at a time, pacing the calls to respect the rate limit.
+   * Yields `{ email, result }` or `{ email, error }` for each non-empty address.
+   */
+  async *verifyMany(emails, options = {}) {
+    const delayMs = options.delayMs ?? (this.isFree ? 3e4 : 1e3);
+    const retryOnLimit = options.retryOnLimit ?? true;
+    let first = true;
+    for await (const raw of emails) {
+      const email = String(raw).trim();
+      if (!email) continue;
+      if (!first && delayMs > 0) await sleep(delayMs);
+      first = false;
+      try {
+        yield { email, result: await this.verify(email) };
+      } catch (err) {
+        if (retryOnLimit && err instanceof MailTesterRateLimitError && err.retryAfterSeconds !== void 0) {
+          await sleep((err.retryAfterSeconds + 1) * 1e3);
+          try {
+            yield { email, result: await this.verify(email) };
+          } catch (err2) {
+            yield { email, error: err2 instanceof MailTesterError ? err2 : new MailTesterError(String(err2)) };
+          }
+        } else {
+          yield { email, error: err instanceof MailTesterError ? err : new MailTesterError(String(err)) };
+        }
+      }
+    }
+  }
+};
+var index_default = MailTester;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_URL,
+  FREE_KEY,
+  MailTester,
+  MailTesterError,
+  MailTesterKeyError,
+  MailTesterRateLimitError,
+  VERSION
+});

package/dist/index.d.cts

@@ -0,0 +1,135 @@
+/**
+ * Official JavaScript and TypeScript client for the MailTester Ninja email verification API.
+ * https://mailtester.ninja/api/
+ */
+declare const VERSION = "1.1.0";
+declare const DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
+/** Keyless free tier: 10 checks a day per IP, one request every 30 seconds. */
+declare const FREE_KEY = "free";
+/** `ok` valid and deliverable, `ko` invalid, `mb` uncertain (catch-all or not probeable). */
+type Verdict = 'ok' | 'ko' | 'mb';
+interface VerificationResult {
+    /** Machine-readable verdict. */
+    code: Verdict;
+    /** Human-readable label: Accepted, Rejected, Catch-All, No MX, Disposable, Timeout... */
+    message: string;
+    /** The address that was checked. */
+    email: string;
+    /** A human-readable guess of the name, derived from the address. */
+    user?: string;
+    domain?: string | null;
+    /** Mail server used for the check. */
+    mx?: string;
+    /** Simultaneous connections used by the key. */
+    connections?: number;
+    /** Daily limit of the key. */
+    limit?: number;
+    /** Requests made with the key over the last 10 seconds. */
+    rate?: number;
+}
+/** Result of a Finder API search (`find`). Check `found` first. */
+interface FindResult {
+    /** `ok` found, `ko` not found, `mb` uncertain (catch-all domain, personal email provider, server not checked). */
+    code: Verdict;
+    /** Accepted, Rejected, Catch-All, Limited, No MX, Disposable, SPAM Block, Timeout, Webmail... */
+    message: string;
+    /** True when the mail server accepted one of the formats. */
+    found: boolean;
+    /** The address found, otherwise null. */
+    email: string | null;
+    /** Pattern of the returned address (email, or guess when not found): first.last, flast, first, firstlast, first_last or f.last. */
+    format: string | null;
+    /** For an address found: `high` (first and last name in it), `medium` (an initial, a namesake may share it), `low` (first name only). */
+    confidence: 'high' | 'medium' | 'low' | null;
+    /** Not verified: on a catch-all domain the most common format, for a full mailbox (Limited) that address. */
+    guess: string | null;
+    first: string;
+    last: string;
+    /** The normalised domain that was searched. */
+    domain: string;
+    /** Mail server used for the search. */
+    mx: string;
+    /** Address formats tested, each one counted as a verification, even when nothing is found. */
+    permutations: number;
+    /** Every address tested, in order, with its verdict. */
+    tested: {
+        email: string;
+        code: string;
+        message: string;
+    }[];
+    /** Simultaneous connections used by the key. */
+    connections?: number;
+    /** Daily limit of the key. */
+    limit?: number;
+    /** Verifications made with the key over the last 10 seconds, permutations included. */
+    rate?: number;
+    /** Seconds taken by the search. */
+    duration?: number;
+    /** Why nothing was found, in plain English. Null when found. */
+    reason: string | null;
+}
+interface MailTesterOptions {
+    /**
+     * `free` (no signup), a free token `mtf_...` from https://mailtester.ninja/free-email-verification-api/,
+     * or a subscription key `sub_...`. Defaults to the MAILTESTER_KEY environment variable, then `free`.
+     */
+    key?: string;
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default 60000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (tests, proxies). Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+interface VerifyManyOptions {
+    /** Pause between calls in milliseconds. Default: 30000 on the free tier, 1000 with a paid key. */
+    delayMs?: number;
+    /** On a free tier limit (HTTP 429), wait the announced time and retry once. Default true. */
+    retryOnLimit?: boolean;
+}
+interface VerifyManyItem {
+    email: string;
+    result?: VerificationResult;
+    error?: MailTesterError;
+}
+/** Any error returned by the API or the network. Never a verdict: do not drop the address on it. */
+declare class MailTesterError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/** The key is invalid or disabled (`code` "--"). */
+declare class MailTesterKeyError extends MailTesterError {
+    constructor(message: string, status?: number);
+}
+/** A limit was reached (HTTP 429). `retryAfterSeconds` is set when the API says how long to wait. */
+declare class MailTesterRateLimitError extends MailTesterError {
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, retryAfterSeconds?: number);
+}
+declare class MailTester {
+    readonly key: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    private readonly fetchImpl;
+    constructor(options?: MailTesterOptions | string);
+    /** True on the free tier (`free` or a free token), limited to one request every 30 seconds. */
+    get isFree(): boolean;
+    private request;
+    /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
+    verify(email: string): Promise<VerificationResult>;
+    /**
+     * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+     * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+     * and returns the first address the mail server accepts. Each format tested counts as one verification.
+     * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+     */
+    find(first: string, last: string, domain: string): Promise<FindResult>;
+    /** True only when the address is clearly valid and deliverable (`code` "ok"). */
+    isDeliverable(email: string): Promise<boolean>;
+    /**
+     * Verify a list, one address at a time, pacing the calls to respect the rate limit.
+     * Yields `{ email, result }` or `{ email, error }` for each non-empty address.
+     */
+    verifyMany(emails: Iterable<string> | AsyncIterable<string>, options?: VerifyManyOptions): AsyncGenerator<VerifyManyItem>;
+}
+
+export { DEFAULT_BASE_URL, FREE_KEY, type FindResult, MailTester, MailTesterError, MailTesterKeyError, type MailTesterOptions, MailTesterRateLimitError, VERSION, type Verdict, type VerificationResult, type VerifyManyItem, type VerifyManyOptions, MailTester as default };

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Official JavaScript and TypeScript client for the MailTester Ninja email verification API.
+ * https://mailtester.ninja/api/
+ */
+declare const VERSION = "1.1.0";
+declare const DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
+/** Keyless free tier: 10 checks a day per IP, one request every 30 seconds. */
+declare const FREE_KEY = "free";
+/** `ok` valid and deliverable, `ko` invalid, `mb` uncertain (catch-all or not probeable). */
+type Verdict = 'ok' | 'ko' | 'mb';
+interface VerificationResult {
+    /** Machine-readable verdict. */
+    code: Verdict;
+    /** Human-readable label: Accepted, Rejected, Catch-All, No MX, Disposable, Timeout... */
+    message: string;
+    /** The address that was checked. */
+    email: string;
+    /** A human-readable guess of the name, derived from the address. */
+    user?: string;
+    domain?: string | null;
+    /** Mail server used for the check. */
+    mx?: string;
+    /** Simultaneous connections used by the key. */
+    connections?: number;
+    /** Daily limit of the key. */
+    limit?: number;
+    /** Requests made with the key over the last 10 seconds. */
+    rate?: number;
+}
+/** Result of a Finder API search (`find`). Check `found` first. */
+interface FindResult {
+    /** `ok` found, `ko` not found, `mb` uncertain (catch-all domain, personal email provider, server not checked). */
+    code: Verdict;
+    /** Accepted, Rejected, Catch-All, Limited, No MX, Disposable, SPAM Block, Timeout, Webmail... */
+    message: string;
+    /** True when the mail server accepted one of the formats. */
+    found: boolean;
+    /** The address found, otherwise null. */
+    email: string | null;
+    /** Pattern of the returned address (email, or guess when not found): first.last, flast, first, firstlast, first_last or f.last. */
+    format: string | null;
+    /** For an address found: `high` (first and last name in it), `medium` (an initial, a namesake may share it), `low` (first name only). */
+    confidence: 'high' | 'medium' | 'low' | null;
+    /** Not verified: on a catch-all domain the most common format, for a full mailbox (Limited) that address. */
+    guess: string | null;
+    first: string;
+    last: string;
+    /** The normalised domain that was searched. */
+    domain: string;
+    /** Mail server used for the search. */
+    mx: string;
+    /** Address formats tested, each one counted as a verification, even when nothing is found. */
+    permutations: number;
+    /** Every address tested, in order, with its verdict. */
+    tested: {
+        email: string;
+        code: string;
+        message: string;
+    }[];
+    /** Simultaneous connections used by the key. */
+    connections?: number;
+    /** Daily limit of the key. */
+    limit?: number;
+    /** Verifications made with the key over the last 10 seconds, permutations included. */
+    rate?: number;
+    /** Seconds taken by the search. */
+    duration?: number;
+    /** Why nothing was found, in plain English. Null when found. */
+    reason: string | null;
+}
+interface MailTesterOptions {
+    /**
+     * `free` (no signup), a free token `mtf_...` from https://mailtester.ninja/free-email-verification-api/,
+     * or a subscription key `sub_...`. Defaults to the MAILTESTER_KEY environment variable, then `free`.
+     */
+    key?: string;
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default 60000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (tests, proxies). Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+interface VerifyManyOptions {
+    /** Pause between calls in milliseconds. Default: 30000 on the free tier, 1000 with a paid key. */
+    delayMs?: number;
+    /** On a free tier limit (HTTP 429), wait the announced time and retry once. Default true. */
+    retryOnLimit?: boolean;
+}
+interface VerifyManyItem {
+    email: string;
+    result?: VerificationResult;
+    error?: MailTesterError;
+}
+/** Any error returned by the API or the network. Never a verdict: do not drop the address on it. */
+declare class MailTesterError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/** The key is invalid or disabled (`code` "--"). */
+declare class MailTesterKeyError extends MailTesterError {
+    constructor(message: string, status?: number);
+}
+/** A limit was reached (HTTP 429). `retryAfterSeconds` is set when the API says how long to wait. */
+declare class MailTesterRateLimitError extends MailTesterError {
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, retryAfterSeconds?: number);
+}
+declare class MailTester {
+    readonly key: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    private readonly fetchImpl;
+    constructor(options?: MailTesterOptions | string);
+    /** True on the free tier (`free` or a free token), limited to one request every 30 seconds. */
+    get isFree(): boolean;
+    private request;
+    /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
+    verify(email: string): Promise<VerificationResult>;
+    /**
+     * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+     * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+     * and returns the first address the mail server accepts. Each format tested counts as one verification.
+     * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+     */
+    find(first: string, last: string, domain: string): Promise<FindResult>;
+    /** True only when the address is clearly valid and deliverable (`code` "ok"). */
+    isDeliverable(email: string): Promise<boolean>;
+    /**
+     * Verify a list, one address at a time, pacing the calls to respect the rate limit.
+     * Yields `{ email, result }` or `{ email, error }` for each non-empty address.
+     */
+    verifyMany(emails: Iterable<string> | AsyncIterable<string>, options?: VerifyManyOptions): AsyncGenerator<VerifyManyItem>;
+}
+
+export { DEFAULT_BASE_URL, FREE_KEY, type FindResult, MailTester, MailTesterError, MailTesterKeyError, type MailTesterOptions, MailTesterRateLimitError, VERSION, type Verdict, type VerificationResult, type VerifyManyItem, type VerifyManyOptions, MailTester as default };

package/dist/index.js

@@ -0,0 +1,155 @@
+// src/index.ts
+var VERSION = "1.1.0";
+var DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
+var FREE_KEY = "free";
+var MailTesterError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "MailTesterError";
+    this.status = status;
+  }
+};
+var MailTesterKeyError = class extends MailTesterError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "MailTesterKeyError";
+  }
+};
+var MailTesterRateLimitError = class extends MailTesterError {
+  retryAfterSeconds;
+  constructor(message, retryAfterSeconds) {
+    super(message, 429);
+    this.name = "MailTesterRateLimitError";
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function envKey() {
+  const g = globalThis;
+  return g.process?.env?.MAILTESTER_KEY || void 0;
+}
+function parseJson(text) {
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === "object" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function retryAfter(message) {
+  const m = /retry in (\d+)\s*s/i.exec(message);
+  return m ? Number(m[1]) : void 0;
+}
+var MailTester = class {
+  key;
+  baseUrl;
+  timeoutMs;
+  fetchImpl;
+  constructor(options = {}) {
+    const opts = typeof options === "string" ? { key: options } : options;
+    this.key = (opts.key ?? envKey() ?? FREE_KEY).trim().replace(/^\{|\}$/g, "");
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? 6e4;
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f) throw new MailTesterError("No fetch implementation available: use Node.js 18 or later, or pass options.fetch");
+    this.fetchImpl = f;
+  }
+  /** True on the free tier (`free` or a free token), limited to one request every 30 seconds. */
+  get isFree() {
+    return this.key === FREE_KEY || this.key.startsWith("mtf_");
+  }
+  async request(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, { headers: { Accept: "application/json" }, signal: controller.signal });
+    } catch (err) {
+      const aborted = err?.name === "AbortError";
+      throw new MailTesterError(aborted ? `Request timed out after ${this.timeoutMs} ms` : `Network error: ${String(err?.message ?? err)}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    return { res, text, body: parseJson(text) };
+  }
+  /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
+  async verify(email) {
+    const { res, text, body } = await this.request(`${this.baseUrl}/ninja?email=${encodeURIComponent(email.trim())}&key=${encodeURIComponent(this.key)}`);
+    const message = typeof body?.message === "string" ? body.message : text.trim();
+    if (res.status === 429) throw new MailTesterRateLimitError(message, retryAfter(message));
+    if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
+    if (!body) throw new MailTesterError("Unexpected response from the API", res.status);
+    if (body.code === "--") throw new MailTesterKeyError(message, res.status);
+    return body;
+  }
+  /**
+   * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+   * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+   * and returns the first address the mail server accepts. Each format tested counts as one verification.
+   * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+   */
+  async find(first, last, domain) {
+    if (this.isFree) {
+      throw new MailTesterKeyError("The Finder API needs a paid key: https://mailtester.ninja/verify-emails-unlimited/", 403);
+    }
+    const qs = new URLSearchParams({ first: first.trim(), last: last.trim(), domain: domain.trim(), key: this.key });
+    const { res, text, body } = await this.request(`${this.baseUrl}/find?${qs}`);
+    const reason = typeof body?.reason === "string" && body.reason ? body.reason : void 0;
+    const message = reason ?? (typeof body?.message === "string" ? body.message : text.trim());
+    if (res.status === 429) {
+      const wait = Number(res.headers.get("retry-after"));
+      throw new MailTesterRateLimitError(message, Number.isFinite(wait) && wait > 0 ? wait : void 0);
+    }
+    if (res.status === 403 && body) throw new MailTesterKeyError(message, 403);
+    if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
+    if (!body) throw new MailTesterError("Unexpected response from the API", res.status);
+    if (body.code === "--") throw new MailTesterKeyError(message, res.status);
+    return body;
+  }
+  /** True only when the address is clearly valid and deliverable (`code` "ok"). */
+  async isDeliverable(email) {
+    return (await this.verify(email)).code === "ok";
+  }
+  /**
+   * Verify a list, one address at a time, pacing the calls to respect the rate limit.
+   * Yields `{ email, result }` or `{ email, error }` for each non-empty address.
+   */
+  async *verifyMany(emails, options = {}) {
+    const delayMs = options.delayMs ?? (this.isFree ? 3e4 : 1e3);
+    const retryOnLimit = options.retryOnLimit ?? true;
+    let first = true;
+    for await (const raw of emails) {
+      const email = String(raw).trim();
+      if (!email) continue;
+      if (!first && delayMs > 0) await sleep(delayMs);
+      first = false;
+      try {
+        yield { email, result: await this.verify(email) };
+      } catch (err) {
+        if (retryOnLimit && err instanceof MailTesterRateLimitError && err.retryAfterSeconds !== void 0) {
+          await sleep((err.retryAfterSeconds + 1) * 1e3);
+          try {
+            yield { email, result: await this.verify(email) };
+          } catch (err2) {
+            yield { email, error: err2 instanceof MailTesterError ? err2 : new MailTesterError(String(err2)) };
+          }
+        } else {
+          yield { email, error: err instanceof MailTesterError ? err : new MailTesterError(String(err)) };
+        }
+      }
+    }
+  }
+};
+var index_default = MailTester;
+export {
+  DEFAULT_BASE_URL,
+  FREE_KEY,
+  MailTester,
+  MailTesterError,
+  MailTesterKeyError,
+  MailTesterRateLimitError,
+  VERSION,
+  index_default as default
+};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@mailtester-ninja/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Official client for the MailTester Ninja email verification API: check in real time if an email address is valid and deliverable.",
+  "keywords": [
+    "email",
+    "email-verification",
+    "email-validation",
+    "email-verifier",
+    "email-checker",
+    "smtp",
+    "catch-all",
+    "disposable-email",
+    "mailtester",
+    "api-client"
+  ],
+  "homepage": "https://mailtester.ninja/api/",
+  "bugs": {
+    "url": "https://github.com/mailtester-ninja/mailtester-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mailtester-ninja/mailtester-js.git"
+  },
+  "license": "MIT",
+  "author": "MailTester Ninja (https://mailtester.ninja)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --target node18",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.10",
+    "tsup": "8.3.5",
+    "typescript": "5.6.3",
+    "vitest": "2.1.8"
+  }
+}