@konfeature/ap-email-guessr 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# ap-email-guessr
+
+An [Activepieces](https://www.activepieces.com) community piece that finds a person's email
+address from their name and company domain. It ships two actions:
+
+| Action | What it does |
+| --- | --- |
+| **Generate Email List** | Builds likely addresses from a first name, last name and domain, ordered by real-world corporate naming frequency (`john.doe@`, `jdoe@`, `john@`, ...). |
+| **Find Email** | Generates the candidates, then verifies them top-down — stopping at the first hit or on a catch-all domain — routing Microsoft domains through a free O365 check and everything else through [no2bounce](https://www.no2bounce.com). Returns the found address, a verdict and the credits spent. |
+
+## Setup
+
+The piece auth is an optional **no2bounce API Token** (Settings → API in no2bounce). It is only
+needed to verify **non-Microsoft** domains; Microsoft-backed domains are verified for free via the
+O365 account check, so the token can be left empty if you only target those.
+
+## Actions
+
+### Generate Email List
+
+Inputs: `firstName`, `lastName`, `domain`, plus optional `patternSet` (`common` ≈ 10 patterns /
+`all` ≈ 20, default `all`) and `maxVariants` (hard cap).
+
+Output — candidates ordered most-likely first:
+
+```json
+{ "emails": ["john.doe@example.com", "jdoe@example.com", "john@example.com"], "count": 3 }
+```
+
+Names are normalized (accents stripped, lowercased, non-alphanumerics removed) and the domain is
+cleaned of protocol/path/leading `@`.
+
+### Find Email
+
+Inputs:
+
+- `firstName`, `lastName`, `domain` (required).
+- `patternSet` (optional, default `common`) — `common` checks only the ~10 highest-probability
+  patterns; `all` considers the full ~20.
+- `maxChecks` (optional) — hard ceiling on how many candidates are verified before giving up. This
+  is the per-person credit cap.
+- `useO365` (optional, default `true`) — verify Microsoft-backed domains with the free Azure AD
+  account check instead of spending no2bounce credits.
+- `timeout` (optional, default `15`) — per-request timeout in seconds.
+
+Output:
+
+```json
+{
+    "found": true,
+    "email": "jessie.han@cupshe.com",
+    "status": "valid",
+    "confidence": 0.9,
+    "catchAll": false,
+    "domain": "cupshe.com",
+    "mxProvider": "microsoft",
+    "verifier": "o365",
+    "reason": "o365_valid",
+    "creditsUsed": 0,
+    "candidatesChecked": 1,
+    "candidatesConsidered": 10,
+    "attempts": [{ "email": "jessie.han@cupshe.com", "verdict": "valid", "reason": "account_exists" }]
+}
+```
+
+## How verification works
+
+**Routing.** Per domain the piece resolves MX and fingerprints the provider:
+
+- **Microsoft-backed** (Microsoft/consumer MX, or a `Managed` Azure AD realm on a domain that is
+  *not* a known non-Microsoft mailbox host) → the **free O365 check** (`GetCredentialType`). No port
+  25, no credits. The "Managed realm on a Google/Zoho domain" case is deliberately excluded — that
+  is a leftover tenant, not Microsoft mail, and trusting it produces false negatives.
+- **Everything else** → **no2bounce**. no2bounce is async: submit a 1-email batch to get a
+  `trackingId` (under `data`), then poll `?trackingId=` until the top-level `overallStatus` is
+  `Completed`. For a single email the top-level counts — `Deliverable`, `Undeliverable`,
+  `Deliverable/AcceptAll`, `UnDeliverable/AcceptAll`, `Risky/AcceptAll` — are that email's verdict.
+
+**Credit minimization.** Candidates are verified in likelihood order and the search:
+
+1. **uses no2bounce's per-address catch-all scoring** — on an accept-all domain a predicted-deliverable
+   address counts as a hit (with reduced confidence), a predicted-undeliverable one is skipped, and a
+   genuinely `Risky/AcceptAll` result stops the search;
+2. **verifies non-Microsoft candidates in concurrent rounds of 5 and stops at the first round with a
+   hit** (early-stop) — checking 5 at a time is faster than one-by-one, but since no2bounce bills per
+   email with no refund a round is paid for in full once submitted (a hit at candidate #3 still costs
+   the first round of 5), so the search stops as soon as a round yields a valid address or a catch-all
+   rather than walking the whole list;
+3. uses the **`common` pattern set** by default, capping the not-found tail at ~10 instead of ~20.
+
+no2bounce bills **1 credit per verified email**; the O365 path is **0 credits**. The actual spend is
+returned as `creditsUsed`.
+
+## Verdicts
+
+| `status` | Meaning |
+| --- | --- |
+| `valid` | The mailbox exists (`found: true`, with `email`). |
+| `invalid` | No candidate verified, or null MX / no MX. |
+| `catch_all` | Domain accepts everything — the specific address can't be confirmed. |
+| `unknown` | Verification was inconclusive (e.g. no2bounce token missing, poll timeout, O365 throttled). |
+
+> **Note.** The no2bounce wire format above is confirmed against the live API (the published docs were
+> out of date). The O365 (`login.microsoftonline.com`) check and DNS use only Node built-ins; the only
+> external dependency is the no2bounce HTTP API.
+
+## Build
+
+```sh
+npm install   # or: bun install
+npm run build # tsc -> dist/
+```
+
+The compiled entry point is `dist/src/index.js` (referenced by `main` in `package.json`).
+
+## Publish & install in self-hosted Activepieces
+
+1. Set a unique package name in `package.json` if `ap-email-guessr` is taken on npm, then publish:
+
+    ```sh
+    npm publish --access public
+    ```
+
+2. In your self-hosted Activepieces instance, add the piece from npm
+   (**Platform Admin → Pieces → Install**, or set `AP_DEV_PIECES` when developing) using the
+   published package name and version.
+
+See the Activepieces docs for details: <https://www.activepieces.com/docs/build-pieces/building-pieces/piece-definition>

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export declare const emailGuessr: import("@activepieces/pieces-framework").Piece<import("@activepieces/pieces-framework").SecretTextProperty<false>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emailGuessr = void 0;
+const pieces_framework_1 = require("@activepieces/pieces-framework");
+const find_email_1 = require("./lib/actions/find-email");
+const generate_emails_1 = require("./lib/actions/generate-emails");
+exports.emailGuessr = (0, pieces_framework_1.createPiece)({
+    displayName: "Email Guessr",
+    description: "Generate likely email addresses from a name and domain, then find the real one — free Microsoft 365 checks plus no2bounce verification, with early-stop to minimize credits.",
+    auth: pieces_framework_1.PieceAuth.SecretText({
+        displayName: "no2bounce API Token",
+        description: "API token from no2bounce, used to verify non-Microsoft domains. Optional: Microsoft-backed domains are verified for free via the O365 account check.",
+        required: false,
+    }),
+    minimumSupportedRelease: "0.82.0",
+    logoUrl: "https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/72x72/2709.png",
+    authors: ["frak"],
+    actions: [generate_emails_1.generateEmails, find_email_1.findEmailAction],
+    triggers: [],
+});
+//# sourceMappingURL=index.js.map

package/dist/src/lib/actions/find-email.d.ts

@@ -0,0 +1,10 @@
+export declare const findEmailAction: import("@activepieces/pieces-framework").IAction<import("@activepieces/pieces-framework").PieceAuthProperty, {
+    firstName: import("@activepieces/pieces-framework").ShortTextProperty<true>;
+    lastName: import("@activepieces/pieces-framework").ShortTextProperty<true>;
+    domain: import("@activepieces/pieces-framework").ShortTextProperty<true>;
+    patternSet: import("@activepieces/pieces-framework").StaticDropdownProperty<string, false>;
+    maxChecks: import("@activepieces/pieces-framework").NumberProperty<false>;
+    useO365: import("@activepieces/pieces-framework").CheckboxProperty<false>;
+    timeout: import("@activepieces/pieces-framework").NumberProperty<false>;
+}>;
+//# sourceMappingURL=find-email.d.ts.map

package/dist/src/lib/actions/find-email.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findEmailAction = void 0;
+const pieces_framework_1 = require("@activepieces/pieces-framework");
+const find_person_1 = require("../common/find-person");
+exports.findEmailAction = (0, pieces_framework_1.createAction)({
+    name: "find_email",
+    displayName: "Find Email",
+    description: "Find a person's email from their name and company domain. Generates likely addresses (ordered by real-world frequency), then verifies them top-down — stopping at the first hit or on a catch-all domain — routing Microsoft domains through the free O365 check and everything else through no2bounce.",
+    props: {
+        firstName: pieces_framework_1.Property.ShortText({
+            displayName: "First Name",
+            description: "e.g. John (accents and casing are normalized).",
+            required: true,
+        }),
+        lastName: pieces_framework_1.Property.ShortText({
+            displayName: "Last Name",
+            description: "e.g. Doe (accents and casing are normalized).",
+            required: true,
+        }),
+        domain: pieces_framework_1.Property.ShortText({
+            displayName: "Domain",
+            description: "Company domain, e.g. example.com.",
+            required: true,
+        }),
+        patternSet: pieces_framework_1.Property.StaticDropdown({
+            displayName: "Pattern Set",
+            description: "Common checks only the ~10 highest-probability patterns (fewer credits); All considers the full ~20.",
+            required: false,
+            defaultValue: "common",
+            options: {
+                options: [
+                    { label: "Common only (~10)", value: "common" },
+                    { label: "All patterns (~20)", value: "all" },
+                ],
+            },
+        }),
+        maxChecks: pieces_framework_1.Property.Number({
+            displayName: "Max Verifications (credit cap)",
+            description: "Hard ceiling on how many candidates are verified before giving up. Caps no2bounce credits spent per person.",
+            required: false,
+        }),
+        useO365: pieces_framework_1.Property.Checkbox({
+            displayName: "Use O365 Check",
+            description: "Verify Microsoft-backed domains via the free Azure AD account check instead of spending no2bounce credits.",
+            required: false,
+            defaultValue: true,
+        }),
+        timeout: pieces_framework_1.Property.Number({
+            displayName: "Timeout (seconds)",
+            description: "Per-request timeout for verification calls (1-120).",
+            required: false,
+            defaultValue: 15,
+        }),
+    },
+    async run(context) {
+        const { firstName, lastName, domain, patternSet, maxChecks, useO365 } = context.propsValue;
+        const timeoutSeconds = context.propsValue.timeout ?? 15;
+        const timeoutMs = Math.min(Math.max(Number(timeoutSeconds) || 15, 1), 120) * 1000;
+        const token = context.auth || undefined;
+        const result = await (0, find_person_1.findPersonEmail)(firstName, lastName, domain, {
+            patternSet: patternSet ?? "common",
+            maxChecks: maxChecks != null ? Math.max(1, Number(maxChecks)) : undefined,
+            stopOnFirstHit: true,
+            timeoutMs,
+            useO365: useO365 ?? true,
+            no2bounceToken: token,
+        });
+        return {
+            found: result.found,
+            email: result.email,
+            status: result.verdict,
+            confidence: result.confidence,
+            catchAll: result.catchAll,
+            domain: result.domain,
+            mxProvider: result.mxProvider,
+            verifier: result.verifierUsed,
+            reason: result.reason,
+            creditsUsed: result.creditsUsed,
+            candidatesChecked: result.candidatesChecked,
+            candidatesConsidered: result.candidatesConsidered,
+            attempts: result.attempts.map((attempt) => ({
+                email: attempt.email,
+                verdict: attempt.verdict,
+                reason: attempt.reason,
+            })),
+        };
+    },
+});
+//# sourceMappingURL=find-email.js.map

package/dist/src/lib/actions/generate-emails.d.ts

@@ -0,0 +1,8 @@
+export declare const generateEmails: import("@activepieces/pieces-framework").IAction<import("@activepieces/pieces-framework").PieceAuthProperty, {
+    firstName: import("@activepieces/pieces-framework").ShortTextProperty<true>;
+    lastName: import("@activepieces/pieces-framework").ShortTextProperty<true>;
+    domain: import("@activepieces/pieces-framework").ShortTextProperty<true>;
+    patternSet: import("@activepieces/pieces-framework").StaticDropdownProperty<string, false>;
+    maxVariants: import("@activepieces/pieces-framework").NumberProperty<false>;
+}>;
+//# sourceMappingURL=generate-emails.d.ts.map

package/dist/src/lib/actions/generate-emails.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEmails = void 0;
+const pieces_framework_1 = require("@activepieces/pieces-framework");
+const patterns_1 = require("../common/patterns");
+exports.generateEmails = (0, pieces_framework_1.createAction)({
+    name: "generate_emails",
+    displayName: "Generate Email List",
+    description: "Build a list of likely email addresses from a first name, last name and domain, ordered by real-world corporate naming frequency (most likely first).",
+    props: {
+        firstName: pieces_framework_1.Property.ShortText({
+            displayName: "First Name",
+            description: "e.g. John (accents and casing are normalized).",
+            required: true,
+        }),
+        lastName: pieces_framework_1.Property.ShortText({
+            displayName: "Last Name",
+            description: "e.g. Doe (accents and casing are normalized).",
+            required: true,
+        }),
+        domain: pieces_framework_1.Property.ShortText({
+            displayName: "Domain",
+            description: "Company domain, e.g. example.com.",
+            required: true,
+        }),
+        patternSet: pieces_framework_1.Property.StaticDropdown({
+            displayName: "Pattern Set",
+            description: "Common keeps only the ~10 highest-probability patterns (cheaper to verify); All returns the full ~20 ordered patterns.",
+            required: false,
+            defaultValue: "all",
+            options: {
+                options: [
+                    { label: "All patterns (~20)", value: "all" },
+                    { label: "Common only (~10)", value: "common" },
+                ],
+            },
+        }),
+        maxVariants: pieces_framework_1.Property.Number({
+            displayName: "Max Variants",
+            description: "Optional hard cap on the number of candidates returned, applied after ordering.",
+            required: false,
+        }),
+    },
+    async run(context) {
+        const { firstName, lastName, domain, patternSet, maxVariants } = context.propsValue;
+        const emails = (0, patterns_1.generateEmailCandidates)({
+            firstName,
+            lastName,
+            domain,
+            patternSet: patternSet ?? "all",
+            maxVariants: maxVariants != null ? Number(maxVariants) : undefined,
+        });
+        return { emails, count: emails.length };
+    },
+});
+//# sourceMappingURL=generate-emails.js.map

package/dist/src/lib/common/dns.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Domain mail-routing resolution (DNS only, Node built-ins).
+ *
+ * Used by the verifier router to fingerprint the provider and detect domains
+ * that cannot receive mail (no MX, or an explicit RFC 7505 null MX).
+ */
+export interface MailRouting {
+    /** MX hosts ordered by priority (or the domain itself for implicit MX). */
+    hosts: string[];
+    /** RFC 7505 null MX: the domain explicitly accepts no mail. */
+    nullMx: boolean;
+}
+export declare function resolveMail(domain: string): Promise<MailRouting>;
+//# sourceMappingURL=dns.d.ts.map

package/dist/src/lib/common/dns.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Domain mail-routing resolution (DNS only, Node built-ins).
+ *
+ * Used by the verifier router to fingerprint the provider and detect domains
+ * that cannot receive mail (no MX, or an explicit RFC 7505 null MX).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMail = resolveMail;
+const node_dns_1 = require("node:dns");
+async function resolveMail(domain) {
+    try {
+        const records = await node_dns_1.promises.resolveMx(domain);
+        const real = records.filter((record) => record.exchange && record.exchange !== ".");
+        // Records exist but every exchange is empty/"." → explicit null MX.
+        if (records.length > 0 && real.length === 0) {
+            return { hosts: [], nullMx: true };
+        }
+        if (real.length > 0) {
+            const hosts = real
+                .sort((a, b) => a.priority - b.priority)
+                .map((record) => record.exchange);
+            return { hosts, nullMx: false };
+        }
+    }
+    catch {
+        // No MX records; fall back to the implicit-MX (A/AAAA) lookup below.
+    }
+    try {
+        await node_dns_1.promises.lookup(domain);
+        return { hosts: [domain], nullMx: false };
+    }
+    catch {
+        return { hosts: [], nullMx: false };
+    }
+}
+//# sourceMappingURL=dns.js.map

package/dist/src/lib/common/find-email.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Credit-minimizing email search (layers 1 + 2).
+ *
+ * Candidates arrive pre-ordered by likelihood and are verified top-down in
+ * rounds of `batchSize` (1 = strictly sequential). Each completed round is read
+ * back in candidate order, so the verdict is identical to checking one at a time:
+ *  - stop at the first `valid` hit (layer 2: early-stop), and
+ *  - stop immediately on a `catch_all` verdict, since a catch-all domain the
+ *    verifier can't score further can't disambiguate individual mailboxes —
+ *    continuing would just burn credits for no extra signal (layer 1).
+ *
+ * no2bounce bills per email with no refund, so a round is paid for the moment it
+ * is submitted: `creditsUsed` counts every email in the rounds we started, even
+ * when an early candidate in the final round is the hit. A larger `batchSize` is
+ * thus faster (fewer submit/poll cycles) but coarser on credits. `maxChecks` is a
+ * hard ceiling; a `valid` hit on an accept-all domain is reported with reduced
+ * confidence and `catchAll: true`.
+ */
+import type { Verifier, VerifyOutcome, VerifyVerdict } from "./verifier";
+export interface FindEmailOptions {
+    /** Hard ceiling on verifications (credit cap). Defaults to all candidates. */
+    maxChecks?: number;
+    /** Stop at the first valid hit. Defaults to true. */
+    stopOnFirstHit?: boolean;
+    /** Candidates verified concurrently per round. Defaults to 1 (sequential). */
+    batchSize?: number;
+}
+export interface FindEmailResult {
+    found: boolean;
+    email: string | null;
+    verdict: VerifyVerdict;
+    confidence: number;
+    catchAll: boolean;
+    candidatesChecked: number;
+    creditsUsed: number;
+    attempts: VerifyOutcome[];
+}
+export declare function findEmail(candidates: string[], verifier: Verifier, options?: FindEmailOptions): Promise<FindEmailResult>;
+//# sourceMappingURL=find-email.d.ts.map

package/dist/src/lib/common/find-email.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Credit-minimizing email search (layers 1 + 2).
+ *
+ * Candidates arrive pre-ordered by likelihood and are verified top-down in
+ * rounds of `batchSize` (1 = strictly sequential). Each completed round is read
+ * back in candidate order, so the verdict is identical to checking one at a time:
+ *  - stop at the first `valid` hit (layer 2: early-stop), and
+ *  - stop immediately on a `catch_all` verdict, since a catch-all domain the
+ *    verifier can't score further can't disambiguate individual mailboxes —
+ *    continuing would just burn credits for no extra signal (layer 1).
+ *
+ * no2bounce bills per email with no refund, so a round is paid for the moment it
+ * is submitted: `creditsUsed` counts every email in the rounds we started, even
+ * when an early candidate in the final round is the hit. A larger `batchSize` is
+ * thus faster (fewer submit/poll cycles) but coarser on credits. `maxChecks` is a
+ * hard ceiling; a `valid` hit on an accept-all domain is reported with reduced
+ * confidence and `catchAll: true`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findEmail = findEmail;
+const CONFIDENCE = {
+    valid: 0.9,
+    catch_all: 0.5,
+    invalid: 0.05,
+    unknown: 0.5,
+};
+function result(found, email, verdict, catchAll, attempts, creditsUsed) {
+    // An accept-all "hit" is probabilistic, so trust it less than a clean one.
+    const confidence = verdict === "valid" && catchAll ? 0.6 : CONFIDENCE[verdict];
+    return {
+        found,
+        email,
+        verdict,
+        confidence,
+        catchAll,
+        candidatesChecked: attempts.length,
+        creditsUsed,
+        attempts,
+    };
+}
+async function findEmail(candidates, verifier, options = {}) {
+    const stopOnFirstHit = options.stopOnFirstHit ?? true;
+    const batchSize = Math.max(1, options.batchSize ?? 1);
+    const limit = Math.min(options.maxChecks ?? candidates.length, candidates.length);
+    const attempts = [];
+    let creditsUsed = 0;
+    let firstValid = null;
+    for (let start = 0; start < limit; start += batchSize) {
+        const round = candidates.slice(start, Math.min(start + batchSize, limit));
+        const outcomes = await Promise.all(round.map((email) => verifier.verify(email)));
+        // The whole round is billed on submit (no2bounce charges per email with
+        // no refund), so count every result before deciding the verdict.
+        for (const outcome of outcomes) {
+            attempts.push(outcome);
+            creditsUsed += outcome.creditsUsed;
+        }
+        for (const outcome of outcomes) {
+            if (outcome.verdict === "catch_all") {
+                return result(false, null, "catch_all", true, attempts, creditsUsed);
+            }
+            if (outcome.verdict === "valid") {
+                if (!firstValid) {
+                    firstValid = outcome;
+                }
+                if (stopOnFirstHit) {
+                    return result(true, outcome.email, "valid", outcome.catchAll ?? false, attempts, creditsUsed);
+                }
+            }
+        }
+    }
+    if (firstValid) {
+        return result(true, firstValid.email, "valid", firstValid.catchAll ?? false, attempts, creditsUsed);
+    }
+    const sawUnknown = attempts.some((a) => a.verdict === "unknown");
+    return result(false, null, sawUnknown ? "unknown" : "invalid", attempts.some((a) => a.catchAll === true), attempts, creditsUsed);
+}
+//# sourceMappingURL=find-email.js.map

package/dist/src/lib/common/find-person.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-person email finder: generate ordered candidates, pick the right verifier
+ * for the domain, then run the credit-minimizing early-stop search.
+ *
+ * Routing: use the free O365 account check when mail genuinely routes through
+ * Microsoft (Microsoft/consumer MX, or a "Managed" realm on a domain that is not
+ * a known non-Microsoft mailbox host). Everything else goes to no2bounce. The
+ * "Managed realm but Google/Zoho MX" exclusion is the louyetu.fr false-negative
+ * fix: a leftover Azure AD tenant must not be trusted as Microsoft mail.
+ */
+import { type FindEmailResult } from "./find-email";
+import { type PatternSet } from "./patterns";
+export interface FindPersonOptions {
+    patternSet: PatternSet;
+    maxVariants?: number;
+    /** Hard ceiling on verifications (credit cap). */
+    maxChecks?: number;
+    stopOnFirstHit: boolean;
+    timeoutMs: number;
+    useO365: boolean;
+    no2bounceToken?: string;
+}
+export interface FindPersonResult extends FindEmailResult {
+    reason: string;
+    domain: string;
+    mxProvider: string;
+    verifierUsed: string;
+    candidatesConsidered: number;
+}
+export declare function findPersonEmail(firstName: string, lastName: string, domain: string, options: FindPersonOptions): Promise<FindPersonResult>;
+//# sourceMappingURL=find-person.d.ts.map

package/dist/src/lib/common/find-person.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Per-person email finder: generate ordered candidates, pick the right verifier
+ * for the domain, then run the credit-minimizing early-stop search.
+ *
+ * Routing: use the free O365 account check when mail genuinely routes through
+ * Microsoft (Microsoft/consumer MX, or a "Managed" realm on a domain that is not
+ * a known non-Microsoft mailbox host). Everything else goes to no2bounce. The
+ * "Managed realm but Google/Zoho MX" exclusion is the louyetu.fr false-negative
+ * fix: a leftover Azure AD tenant must not be trusted as Microsoft mail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findPersonEmail = findPersonEmail;
+const dns_1 = require("./dns");
+const find_email_1 = require("./find-email");
+const mx_fingerprint_1 = require("./mx-fingerprint");
+const o365_1 = require("./providers/o365");
+const patterns_1 = require("./patterns");
+const no2bounce_verifier_1 = require("./verifiers/no2bounce-verifier");
+const o365_verifier_1 = require("./verifiers/o365-verifier");
+const NO2BOUNCE_BATCH_SIZE = 5;
+function earlyExit(candidatesConsidered, domain, mxProvider, verdict, confidence, reason) {
+    return {
+        found: false,
+        email: null,
+        verdict,
+        confidence,
+        catchAll: false,
+        candidatesChecked: 0,
+        creditsUsed: 0,
+        attempts: [],
+        reason,
+        domain,
+        mxProvider,
+        verifierUsed: "none",
+        candidatesConsidered,
+    };
+}
+async function findPersonEmail(firstName, lastName, domain, options) {
+    const candidates = (0, patterns_1.generateEmailCandidates)({
+        firstName,
+        lastName,
+        domain,
+        patternSet: options.patternSet,
+        maxVariants: options.maxVariants,
+    });
+    const cleanDomain = (0, patterns_1.normalizeDomain)(domain);
+    if (candidates.length === 0) {
+        return earlyExit(0, cleanDomain, "none", "invalid", 0.03, "no_candidates");
+    }
+    const routing = await (0, dns_1.resolveMail)(cleanDomain);
+    const provider = (0, mx_fingerprint_1.fingerprintMx)(routing.hosts);
+    if (routing.nullMx) {
+        return earlyExit(candidates.length, cleanDomain, provider.id, "invalid", 0.02, "null_mx");
+    }
+    if (routing.hosts.length === 0) {
+        return earlyExit(candidates.length, cleanDomain, provider.id, "invalid", 0.03, "no_mx_record");
+    }
+    const consumer = (0, o365_1.isMicrosoftConsumerDomain)(cleanDomain);
+    let namespace = null;
+    let microsoftBacked = consumer || provider.microsoftBacked;
+    // Only spend a realm lookup on ambiguous MX (not obviously Microsoft, not a
+    // known foreign mailbox host) — that's where O365-behind-a-gateway hides.
+    if (options.useO365 &&
+        !microsoftBacked &&
+        !(0, mx_fingerprint_1.hostsNonMicrosoftMailboxes)(provider)) {
+        namespace = await (0, o365_1.getUserRealm)(cleanDomain, options.timeoutMs);
+        if (namespace === "Managed") {
+            microsoftBacked = true;
+        }
+    }
+    let verifier;
+    let verifierUsed;
+    if (options.useO365 && microsoftBacked) {
+        verifier = (0, o365_verifier_1.createO365Verifier)(namespace ?? "Managed", true, options.timeoutMs);
+        verifierUsed = "o365";
+    }
+    else if (options.no2bounceToken) {
+        verifier = (0, no2bounce_verifier_1.createNo2BounceVerifier)({
+            apitoken: options.no2bounceToken,
+            timeoutMs: options.timeoutMs,
+        });
+        verifierUsed = "no2bounce";
+    }
+    else {
+        return earlyExit(candidates.length, cleanDomain, provider.id, "unknown", 0.5, "no2bounce_token_required");
+    }
+    const result = await (0, find_email_1.findEmail)(candidates, verifier, {
+        maxChecks: options.maxChecks,
+        stopOnFirstHit: options.stopOnFirstHit,
+        batchSize: verifierUsed === "no2bounce" ? NO2BOUNCE_BATCH_SIZE : 1,
+    });
+    return {
+        ...result,
+        reason: `${verifierUsed}_${result.verdict}`,
+        domain: cleanDomain,
+        mxProvider: provider.id,
+        verifierUsed,
+        candidatesConsidered: candidates.length,
+    };
+}
+//# sourceMappingURL=find-person.js.map

package/dist/src/lib/common/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal HTTPS client built on Node's `node:https` only (no dependencies).
+ * Used by the provider signal collectors (O365, Gravatar). Designed to fail
+ * soft: callers treat any network/timeout error as a neutral signal rather
+ * than a hard verdict.
+ */
+export interface HttpResponse {
+    status: number;
+    body: string;
+}
+export interface HttpRequestOptions {
+    url: string;
+    method?: "GET" | "HEAD" | "POST";
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs: number;
+}
+/**
+ * Perform a single HTTPS request. Resolves with the status code and (for
+ * non-HEAD requests) the response body. Rejects only on transport failure or
+ * timeout so callers can map those to a neutral signal.
+ */
+export declare function httpRequest(options: HttpRequestOptions): Promise<HttpResponse>;
+//# sourceMappingURL=http.d.ts.map