@emailsherlock/node 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 EmailSherlock
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,120 @@
1
+ # @emailsherlock/node
2
+
3
+ Official Node.js client for the [EmailSherlock](https://emailsherlock.com) email-verification API. Verify one address or a batch over HTTPS with an API key.
4
+
5
+ Zero dependencies. Works on Node 18+ (uses the built-in `fetch`).
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @emailsherlock/node
11
+ ```
12
+
13
+ ## Quick start
14
+
15
+ ```js
16
+ import { Emailsherlock } from '@emailsherlock/node';
17
+
18
+ // reads the key from the environment, never hard-code it
19
+ const es = new Emailsherlock(process.env.ES_KEY);
20
+
21
+ const result = await es.verify.single({ email: 'jane@acme.com' });
22
+
23
+ console.log(result.result); // 'valid'
24
+ console.log(result.score); // 0.95
25
+ ```
26
+
27
+ The constructor also reads `ES_KEY` (or `EMAILSHERLOCK_API_KEY`) from the
28
+ environment if you call `new Emailsherlock()` with no argument.
29
+
30
+ ## Batch
31
+
32
+ Up to 100 addresses per call:
33
+
34
+ ```js
35
+ const { results } = await es.verify.batch({
36
+ emails: ['jane@acme.com', 'sales@acme.com'],
37
+ });
38
+
39
+ results[0].result; // 'valid'
40
+ results[1].role; // true
41
+ ```
42
+
43
+ A batch item is either a result object or a per-address error. Narrow it with
44
+ the type guard:
45
+
46
+ ```js
47
+ import { isVerifyResult } from '@emailsherlock/node';
48
+
49
+ for (const item of results) {
50
+ if (isVerifyResult(item)) {
51
+ console.log(item.email, item.result);
52
+ } else {
53
+ console.log(item.email, 'failed:', item.error);
54
+ }
55
+ }
56
+ ```
57
+
58
+ ## The result object
59
+
60
+ | field | type | meaning |
61
+ |--------------|-----------|-----------------------------------------------------------------|
62
+ | `email` | string | the address you sent |
63
+ | `result` | string | `valid` · `invalid` · `catch_all` · `disposable` · `role` · `unknown` |
64
+ | `mx` | boolean | the domain has reachable MX records |
65
+ | `disposable` | boolean | throwaway / temporary-mail provider |
66
+ | `role` | boolean | role address such as `info@` or `sales@` |
67
+ | `catch_all` | boolean | host accepts mail for any local part |
68
+ | `score` | number | 0–1 confidence, higher is safer to send to |
69
+ | `freshness` | string | `fresh` · `cached_recent` · `cached_stale_refreshed` |
70
+
71
+ ## Credits and rate limits
72
+
73
+ After every call the client exposes what the response headers reported:
74
+
75
+ ```js
76
+ es.creditsRemaining; // e.g. 41
77
+ es.rateLimit; // { limit, remaining, reset }
78
+ ```
79
+
80
+ ## Errors
81
+
82
+ Every failure throws a subclass of `EmailsherlockError`:
83
+
84
+ | class | HTTP | when |
85
+ |-----------------------------|------|-----------------------------------------------|
86
+ | `AuthenticationError` | 401 | missing or invalid API key |
87
+ | `ForbiddenError` | 403 | key lacks the endpoint's scope (`requiredScope`) |
88
+ | `InsufficientCreditsError` | 402 | not enough credits (`creditsRequired`, `creditsRemaining`) |
89
+ | `RateLimitError` | 429 | rate limit hit (`retryAfter`, `limit`, `remaining`, `reset`) |
90
+ | `ValidationError` | 400 / 422 | the request body was rejected |
91
+ | `ServiceUnavailableError` | 503 | verify engine unavailable (the credit is auto-refunded) |
92
+
93
+ ```js
94
+ import { RateLimitError } from '@emailsherlock/node';
95
+
96
+ try {
97
+ await es.verify.single({ email: 'jane@acme.com' });
98
+ } catch (err) {
99
+ if (err instanceof RateLimitError) {
100
+ console.log(`retry after ${err.retryAfter}s`);
101
+ } else {
102
+ throw err;
103
+ }
104
+ }
105
+ ```
106
+
107
+ ## Options
108
+
109
+ ```js
110
+ new Emailsherlock({
111
+ apiKey: process.env.ES_KEY,
112
+ baseUrl: 'https://api.emailsherlock.com', // default
113
+ timeoutMs: 30000, // default
114
+ fetch: customFetch, // optional injection
115
+ });
116
+ ```
117
+
118
+ ## License
119
+
120
+ MIT. Full API reference: https://emailsherlock.com/api/docs
@@ -0,0 +1,39 @@
1
+ import type { VerifyResult, BatchResponse, RateLimit } from './types.js';
2
+ export interface ClientOptions {
3
+ /** Your API key. Falls back to ES_KEY / EMAILSHERLOCK_API_KEY in the env. */
4
+ apiKey?: string;
5
+ /** Override the API base URL (e.g. a staging host). */
6
+ baseUrl?: string;
7
+ /** Per-request timeout in milliseconds. Default 30000. */
8
+ timeoutMs?: number;
9
+ /** Inject a fetch implementation. Defaults to the global fetch (Node 18+). */
10
+ fetch?: typeof fetch;
11
+ }
12
+ /** Verify-endpoint methods, reached as `client.verify`. */
13
+ export declare class VerifyResource {
14
+ private readonly client;
15
+ constructor(client: Emailsherlock);
16
+ /** Verify a single address. */
17
+ single(params: {
18
+ email: string;
19
+ }): Promise<VerifyResult>;
20
+ /** Verify up to 100 addresses in one call. */
21
+ batch(params: {
22
+ emails: string[];
23
+ }): Promise<BatchResponse>;
24
+ }
25
+ export declare class Emailsherlock {
26
+ readonly verify: VerifyResource;
27
+ /** Credits left after the most recent request (from X-Credits-Remaining). */
28
+ creditsRemaining: number | null;
29
+ /** Rate-limit window after the most recent request (from X-RateLimit-*). */
30
+ rateLimit: RateLimit;
31
+ private readonly apiKey;
32
+ private readonly baseUrl;
33
+ private readonly timeoutMs;
34
+ private readonly fetchImpl;
35
+ constructor(apiKey?: string | ClientOptions, options?: ClientOptions);
36
+ /** Low-level POST. Most callers should use `client.verify.*` instead. */
37
+ request<T>(path: string, body: unknown): Promise<T>;
38
+ private captureMeta;
39
+ }
package/dist/client.js ADDED
@@ -0,0 +1,106 @@
1
+ import { VERSION } from './version.js';
2
+ import { errorFromResponse, EmailsherlockError } from './errors.js';
3
+ const DEFAULT_BASE_URL = 'https://api.emailsherlock.com';
4
+ function num(value) {
5
+ if (value === null)
6
+ return null;
7
+ const n = Number(value);
8
+ return Number.isFinite(n) ? n : null;
9
+ }
10
+ function safeParse(text) {
11
+ try {
12
+ return JSON.parse(text);
13
+ }
14
+ catch {
15
+ return null;
16
+ }
17
+ }
18
+ /** Verify-endpoint methods, reached as `client.verify`. */
19
+ export class VerifyResource {
20
+ client;
21
+ constructor(client) {
22
+ this.client = client;
23
+ }
24
+ /** Verify a single address. */
25
+ single(params) {
26
+ return this.client.request('/v1/verify/single', { email: params.email });
27
+ }
28
+ /** Verify up to 100 addresses in one call. */
29
+ batch(params) {
30
+ return this.client.request('/v1/verify/batch', { emails: params.emails });
31
+ }
32
+ }
33
+ export class Emailsherlock {
34
+ verify;
35
+ /** Credits left after the most recent request (from X-Credits-Remaining). */
36
+ creditsRemaining = null;
37
+ /** Rate-limit window after the most recent request (from X-RateLimit-*). */
38
+ rateLimit = { limit: null, remaining: null, reset: null };
39
+ apiKey;
40
+ baseUrl;
41
+ timeoutMs;
42
+ fetchImpl;
43
+ constructor(apiKey, options = {}) {
44
+ const opts = typeof apiKey === 'string' ? { ...options, apiKey } : (apiKey ?? {});
45
+ const key = opts.apiKey ?? process.env.ES_KEY ?? process.env.EMAILSHERLOCK_API_KEY;
46
+ if (!key) {
47
+ throw new EmailsherlockError('No API key provided. Pass it to the constructor or set ES_KEY.', { code: 'config_error' });
48
+ }
49
+ const fetchImpl = opts.fetch ?? globalThis.fetch;
50
+ if (!fetchImpl) {
51
+ throw new EmailsherlockError('No fetch implementation available. Use Node 18+ or pass options.fetch.', { code: 'config_error' });
52
+ }
53
+ this.apiKey = key;
54
+ this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
55
+ this.timeoutMs = opts.timeoutMs ?? 30_000;
56
+ this.fetchImpl = fetchImpl;
57
+ this.verify = new VerifyResource(this);
58
+ }
59
+ /** Low-level POST. Most callers should use `client.verify.*` instead. */
60
+ async request(path, body) {
61
+ const controller = new AbortController();
62
+ const timer = setTimeout(() => controller.abort(), this.timeoutMs);
63
+ let res;
64
+ try {
65
+ res = await this.fetchImpl(`${this.baseUrl}${path}`, {
66
+ method: 'POST',
67
+ headers: {
68
+ 'X-API-Key': this.apiKey,
69
+ 'Content-Type': 'application/json',
70
+ 'User-Agent': `emailsherlock-node/${VERSION}`,
71
+ },
72
+ body: JSON.stringify(body),
73
+ signal: controller.signal,
74
+ });
75
+ }
76
+ catch (err) {
77
+ const reason = err instanceof Error ? err.message : String(err);
78
+ throw new EmailsherlockError(`Request to ${path} failed: ${reason}`, {
79
+ code: 'network_error',
80
+ });
81
+ }
82
+ finally {
83
+ clearTimeout(timer);
84
+ }
85
+ this.captureMeta(res.headers);
86
+ const text = await res.text();
87
+ const json = text ? safeParse(text) : null;
88
+ if (!res.ok) {
89
+ throw errorFromResponse(res.status, json, res.headers);
90
+ }
91
+ return json;
92
+ }
93
+ captureMeta(headers) {
94
+ const credits = headers.get('X-Credits-Remaining');
95
+ if (credits !== null) {
96
+ this.creditsRemaining = num(credits);
97
+ }
98
+ if (headers.get('X-RateLimit-Limit') !== null) {
99
+ this.rateLimit = {
100
+ limit: num(headers.get('X-RateLimit-Limit')),
101
+ remaining: num(headers.get('X-RateLimit-Remaining')),
102
+ reset: num(headers.get('X-RateLimit-Reset')),
103
+ };
104
+ }
105
+ }
106
+ }
@@ -0,0 +1,44 @@
1
+ interface ApiErrorEnvelope {
2
+ error?: {
3
+ code?: string;
4
+ message?: string;
5
+ required_scope?: string;
6
+ };
7
+ }
8
+ export interface ErrorOptions {
9
+ status?: number;
10
+ code?: string;
11
+ }
12
+ /** Base class for every error this client throws. */
13
+ export declare class EmailsherlockError extends Error {
14
+ readonly status?: number;
15
+ readonly code?: string;
16
+ constructor(message: string, options?: ErrorOptions);
17
+ }
18
+ /** 401 — missing or invalid API key. */
19
+ export declare class AuthenticationError extends EmailsherlockError {
20
+ }
21
+ /** 403 — the key lacks the scope this endpoint needs. */
22
+ export declare class ForbiddenError extends EmailsherlockError {
23
+ requiredScope?: string;
24
+ }
25
+ /** 402 — not enough credits on the wallet for this request. */
26
+ export declare class InsufficientCreditsError extends EmailsherlockError {
27
+ creditsRequired?: number | null;
28
+ creditsRemaining?: number | null;
29
+ }
30
+ /** 429 — per-key sliding-window rate limit hit. */
31
+ export declare class RateLimitError extends EmailsherlockError {
32
+ retryAfter?: number | null;
33
+ limit?: number | null;
34
+ remaining?: number | null;
35
+ reset?: number | null;
36
+ }
37
+ /** 400 / 422 — the request body was rejected. */
38
+ export declare class ValidationError extends EmailsherlockError {
39
+ }
40
+ /** 503 — the verify engine could not answer; the credit was auto-refunded. */
41
+ export declare class ServiceUnavailableError extends EmailsherlockError {
42
+ }
43
+ export declare function errorFromResponse(status: number, body: ApiErrorEnvelope | null, headers: Headers): EmailsherlockError;
44
+ export {};
package/dist/errors.js ADDED
@@ -0,0 +1,79 @@
1
+ function num(value) {
2
+ if (value === null)
3
+ return null;
4
+ const n = Number(value);
5
+ return Number.isFinite(n) ? n : null;
6
+ }
7
+ /** Base class for every error this client throws. */
8
+ export class EmailsherlockError extends Error {
9
+ status;
10
+ code;
11
+ constructor(message, options = {}) {
12
+ super(message);
13
+ this.name = new.target.name;
14
+ this.status = options.status;
15
+ this.code = options.code;
16
+ Object.setPrototypeOf(this, new.target.prototype);
17
+ }
18
+ }
19
+ /** 401 — missing or invalid API key. */
20
+ export class AuthenticationError extends EmailsherlockError {
21
+ }
22
+ /** 403 — the key lacks the scope this endpoint needs. */
23
+ export class ForbiddenError extends EmailsherlockError {
24
+ requiredScope;
25
+ }
26
+ /** 402 — not enough credits on the wallet for this request. */
27
+ export class InsufficientCreditsError extends EmailsherlockError {
28
+ creditsRequired;
29
+ creditsRemaining;
30
+ }
31
+ /** 429 — per-key sliding-window rate limit hit. */
32
+ export class RateLimitError extends EmailsherlockError {
33
+ retryAfter;
34
+ limit;
35
+ remaining;
36
+ reset;
37
+ }
38
+ /** 400 / 422 — the request body was rejected. */
39
+ export class ValidationError extends EmailsherlockError {
40
+ }
41
+ /** 503 — the verify engine could not answer; the credit was auto-refunded. */
42
+ export class ServiceUnavailableError extends EmailsherlockError {
43
+ }
44
+ export function errorFromResponse(status, body, headers) {
45
+ const envelope = body?.error ?? {};
46
+ const code = envelope.code;
47
+ const message = envelope.message ?? `HTTP ${status}`;
48
+ const opts = { status, code };
49
+ switch (status) {
50
+ case 401:
51
+ return new AuthenticationError(message, opts);
52
+ case 403: {
53
+ const err = new ForbiddenError(message, opts);
54
+ err.requiredScope = envelope.required_scope ?? headers.get('X-Required-Scope') ?? undefined;
55
+ return err;
56
+ }
57
+ case 402: {
58
+ const err = new InsufficientCreditsError(message, opts);
59
+ err.creditsRequired = num(headers.get('X-Credits-Required'));
60
+ err.creditsRemaining = num(headers.get('X-Credits-Remaining'));
61
+ return err;
62
+ }
63
+ case 429: {
64
+ const err = new RateLimitError(message, opts);
65
+ err.retryAfter = num(headers.get('Retry-After'));
66
+ err.limit = num(headers.get('X-RateLimit-Limit'));
67
+ err.remaining = num(headers.get('X-RateLimit-Remaining'));
68
+ err.reset = num(headers.get('X-RateLimit-Reset'));
69
+ return err;
70
+ }
71
+ case 400:
72
+ case 422:
73
+ return new ValidationError(message, opts);
74
+ case 503:
75
+ return new ServiceUnavailableError(message, opts);
76
+ default:
77
+ return new EmailsherlockError(message, opts);
78
+ }
79
+ }
@@ -0,0 +1,8 @@
1
+ export { Emailsherlock, VerifyResource } from './client.js';
2
+ export type { ClientOptions } from './client.js';
3
+ export { VERSION } from './version.js';
4
+ export { EmailsherlockError, AuthenticationError, ForbiddenError, InsufficientCreditsError, RateLimitError, ValidationError, ServiceUnavailableError, } from './errors.js';
5
+ export { isVerifyResult, } from './types.js';
6
+ export type { VerifyResult, VerifyVerdict, Freshness, BatchItem, BatchItemError, BatchResponse, RateLimit, } from './types.js';
7
+ import { Emailsherlock } from './client.js';
8
+ export default Emailsherlock;
package/dist/index.js ADDED
@@ -0,0 +1,6 @@
1
+ export { Emailsherlock, VerifyResource } from './client.js';
2
+ export { VERSION } from './version.js';
3
+ export { EmailsherlockError, AuthenticationError, ForbiddenError, InsufficientCreditsError, RateLimitError, ValidationError, ServiceUnavailableError, } from './errors.js';
4
+ export { isVerifyResult, } from './types.js';
5
+ import { Emailsherlock } from './client.js';
6
+ export default Emailsherlock;
@@ -0,0 +1,39 @@
1
+ /** The verdict for a single address. Mirrors the API `result` enum. */
2
+ export type VerifyVerdict = 'valid' | 'invalid' | 'catch_all' | 'disposable' | 'role' | 'unknown';
3
+ /** How recent the underlying data is. Mirrors the API `freshness` enum. */
4
+ export type Freshness = 'fresh' | 'cached_recent' | 'cached_stale_refreshed';
5
+ /** The result object returned for a verified address. Mirrors the wire JSON. */
6
+ export interface VerifyResult {
7
+ /** The address that was checked. */
8
+ email: string;
9
+ /** valid · invalid · catch_all · disposable · role · unknown */
10
+ result: VerifyVerdict;
11
+ /** The domain has reachable MX records. */
12
+ mx: boolean;
13
+ /** Throwaway / temporary-mail provider. */
14
+ disposable: boolean;
15
+ /** Role address such as info@ or sales@. */
16
+ role: boolean;
17
+ /** Host accepts mail for any local part. */
18
+ catch_all: boolean;
19
+ /** 0–1 confidence, higher is safer to send to. */
20
+ score: number;
21
+ /** fresh · cached_recent · cached_stale_refreshed */
22
+ freshness: Freshness;
23
+ }
24
+ /** A per-address failure inside a batch response. */
25
+ export interface BatchItemError {
26
+ email: string | null;
27
+ error: 'invalid_email' | 'insufficient_credits' | 'verify_unavailable';
28
+ }
29
+ export type BatchItem = VerifyResult | BatchItemError;
30
+ export interface BatchResponse {
31
+ results: BatchItem[];
32
+ }
33
+ /** Type guard: did this batch item verify, or fail? */
34
+ export declare function isVerifyResult(item: BatchItem): item is VerifyResult;
35
+ export interface RateLimit {
36
+ limit: number | null;
37
+ remaining: number | null;
38
+ reset: number | null;
39
+ }
package/dist/types.js ADDED
@@ -0,0 +1,4 @@
1
+ /** Type guard: did this batch item verify, or fail? */
2
+ export function isVerifyResult(item) {
3
+ return item.error === undefined;
4
+ }
@@ -0,0 +1 @@
1
+ export declare const VERSION = "0.1.0";
@@ -0,0 +1 @@
1
+ export const VERSION = '0.1.0';
package/package.json ADDED
@@ -0,0 +1,51 @@
1
+ {
2
+ "name": "@emailsherlock/node",
3
+ "version": "0.1.0",
4
+ "description": "Official Node.js client for the EmailSherlock email-verification API.",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "module": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "dist",
17
+ "README.md",
18
+ "LICENSE"
19
+ ],
20
+ "engines": {
21
+ "node": ">=18"
22
+ },
23
+ "scripts": {
24
+ "build": "tsc -p tsconfig.json",
25
+ "test": "npm run build && node --test test/*.test.mjs",
26
+ "prepublishOnly": "npm run build"
27
+ },
28
+ "keywords": [
29
+ "email",
30
+ "email-verification",
31
+ "email-validation",
32
+ "emailsherlock",
33
+ "mx",
34
+ "smtp",
35
+ "disposable"
36
+ ],
37
+ "homepage": "https://emailsherlock.com/api/docs",
38
+ "bugs": {
39
+ "url": "https://github.com/Emailsherlock1/node/issues"
40
+ },
41
+ "repository": {
42
+ "type": "git",
43
+ "url": "git+https://github.com/Emailsherlock1/node.git"
44
+ },
45
+ "license": "MIT",
46
+ "author": "EmailSherlock",
47
+ "devDependencies": {
48
+ "typescript": "^5.4.0",
49
+ "@types/node": "^20.0.0"
50
+ }
51
+ }