From 903de3ed041c86d21bba0253cfde2952ea193ad8 Mon Sep 17 00:00:00 2001
From: GENTILHOMME Thomas <gentilhomme.thomas@gmail.com>
Date: Tue, 24 Feb 2026 08:12:14 +0100
Subject: [PATCH] feat(contact): expose NsResolver class

---
 .changeset/upset-socks-clean.md       |  5 ++++
 workspaces/contact/README.md          |  2 ++
 workspaces/contact/docs/NsResolver.md | 33 +++++++++++++++++++++++++++
 workspaces/contact/src/index.ts       |  1 +
 4 files changed, 41 insertions(+)
 create mode 100644 .changeset/upset-socks-clean.md
 create mode 100644 workspaces/contact/docs/NsResolver.md

diff --git a/.changeset/upset-socks-clean.md b/.changeset/upset-socks-clean.md
new file mode 100644
index 00000000..1216f918
--- /dev/null
+++ b/.changeset/upset-socks-clean.md
@@ -0,0 +1,5 @@
+---
+"@nodesecure/contact": minor
+---
+
+Expose NsResolver class and add API documentation
diff --git a/workspaces/contact/README.md b/workspaces/contact/README.md
index e5bd8b84..172c9894 100644
--- a/workspaces/contact/README.md
+++ b/workspaces/contact/README.md
@@ -54,6 +54,8 @@ console.log({ illuminated, expired });
 
 ## API
 
+- [NsResolver](./docs/NsResolver.md)
+
 Contact is defined by the following TypeScript interface:
 ```ts
 interface Contact {
diff --git a/workspaces/contact/docs/NsResolver.md b/workspaces/contact/docs/NsResolver.md
new file mode 100644
index 00000000..74394b9c
--- /dev/null
+++ b/workspaces/contact/docs/NsResolver.md
@@ -0,0 +1,33 @@
+# NsResolver
+
+`NsResolver` is a utility class that collects email addresses and detects which ones have **expired domain names** by performing DNS NS record lookups.
+
+It is used internally by `ContactExtractor` but is also exported for direct use.
+
+## Usage example
+
+```ts
+import { NsResolver } from "@nodesecure/contact";
+
+const resolver = new NsResolver();
+
+resolver.registerEmail("alice@valid-domain.com");
+resolver.registerEmail("bob@expired-domain.xyz");
+
+const expired = await resolver.getExpired();
+console.log(expired); // ["bob@expired-domain.xyz"] (if NS lookup fails)
+```
+
+## API
+
+### `new NsResolver()`
+
+Creates a new instance. The DNS resolver is pre-configured to use Cloudflare (`1.1.1.1`) and Google (`8.8.8.8`) public DNS servers.
+
+### `registerEmail(email: string | undefined | null): void`
+
+Registers an email address for later NS resolution. Silently ignores `null`, `undefined`, and blank strings.
+
+### `getExpired(): Promise<string[]>`
+
+Resolves NS records for the domain of every registered email in parallel. Returns the list of emails whose domain **failed** the NS lookup (i.e. the domain is expired or does not exist).
diff --git a/workspaces/contact/src/index.ts b/workspaces/contact/src/index.ts
index bab21de9..d1ba24ab 100644
--- a/workspaces/contact/src/index.ts
+++ b/workspaces/contact/src/index.ts
@@ -2,3 +2,4 @@ export * from "./ContactExtractor.class.ts";
 export {
   compareContact
 } from "./utils/index.ts";
+export { NsResolver } from "./NsResolver.class.ts";