@emailsherlock/node 0.2.1 → 0.3.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/README.md CHANGED
@@ -67,34 +67,52 @@ for (const item of results) {
67
67
  | `catch_all` | boolean | host accepts mail for any local part |
68
68
  | `score` | number / null | 0–1 confidence, higher is safer to send to (`null` when the verdict is `unknown`) |
69
69
  | `freshness` | string | `fresh` · `cached_recent` · `cached_stale_refreshed` |
70
- | `deliverable`| boolean / null | SMTP-proven: `true` only after an SMTP accept, `false` only on a provable failure, `null` when unproven |
71
- | `reason` | string / null | why the verdict came out the way it did, e.g. `mailbox_accepts` · `mailbox_not_found` · `no_mx` · `bad_syntax` · `disposable_provider` · `role_address` · `catch_all_domain` · `greylisted` · `smtp_timeout` · `smtp_unreachable` · `verification_pending` |
72
- | `mx_record` | string / null | the primary MX host for the domain |
73
- | `free_email` | boolean / null | the address belongs to a free webmail provider |
74
- | `checked_at` | string / null | when the check ran, ISO 8601 |
75
- | `domain` | object / null | domain-level intelligence, see below |
76
-
77
- The fields from `deliverable` down are additive and may be missing until the
78
- API rollout completes; once present they are always set but nullable.
79
-
80
- ### The domain object
81
-
82
- | field | type | meaning |
83
- |----------------|-----------|----------------------------------------------------------|
84
- | `name` | string | the domain part of the address |
85
- | `types` | string[] / null | host types: `freemail` · `disposable` · `custom` · `company` · `government` · `education` · `public` · `isp` |
86
- | `score` | number / null | domain trust score, 0-100, higher is better |
87
- | `spf` | boolean / null | the domain publishes an SPF record |
88
- | `dkim` | boolean / null | the domain publishes at least one DKIM key |
89
- | `dmarc` | boolean / null | the domain publishes a DMARC record |
90
- | `dmarc_policy` | string / null | `none` · `quarantine` · `reject` |
91
- | `mta_sts` | boolean / null | the domain publishes an MTA-STS policy |
92
- | `tls_rpt` | boolean / null | the domain publishes a TLS-RPT record |
93
- | `bimi` | boolean / null | the domain publishes a BIMI record |
94
- | `dane` | boolean / null | the MX hosts publish DANE/TLSA records |
95
- | `blacklists` | number / null | DNS blacklists currently listing the domain's mail IPs |
96
- | `dnssec` | string / null | `secure` · `insecure` · `bogus` |
97
- | `caa` | boolean / null | the domain publishes a CAA record |
70
+ | `deliverable`| boolean? | proven via SMTP: `true` accepted, `false` provably bad, `null` unproven |
71
+ | `reason` | string? | why the pipeline decided (`mailbox_accepts`, `greylisted`, …) |
72
+ | `mx_record` | string? | the primary MX host, when one was resolved |
73
+ | `free_email` | boolean? | the domain is a freemail provider |
74
+ | `checked_at` | string? | when the verification ran (ISO 8601) |
75
+ | `domain` | object? | domain-level intelligence (SPF, DKIM, DMARC, score, blacklists, …) |
76
+ | `decision` | object | `{ recommendation: allow·deny·review, reasons[] }` |
77
+
78
+ Every field and model type is generated from the [OpenAPI spec](https://www.hostsherlock.com/api/docs) and exported, so your editor autocompletes the full shape.
79
+
80
+ ## Async jobs
81
+
82
+ For large lists, submit a job and poll it. Every address runs the full pipeline
83
+ including the SMTP probe, so the results carry definitive inbox verdicts:
84
+
85
+ ```js
86
+ const job = await es.verify.submitJob({ emails: ['a@acme.com', 'b@acme.com'] });
87
+
88
+ let status = job;
89
+ while (status.status !== 'completed') {
90
+ await new Promise((r) => setTimeout(r, 2000));
91
+ status = await es.verify.getJob(job.id);
92
+ }
93
+
94
+ console.log(status.results);
95
+ ```
96
+
97
+ ## Account status
98
+
99
+ ```js
100
+ const account = await es.credits();
101
+ account.credits.total; // spendable credits
102
+ account.rateLimit; // { limit, remaining, reset }
103
+ account.sandbox; // true on an es_test_ key
104
+ ```
105
+
106
+ ## Email-Guard events
107
+
108
+ Record Email-Guard decision events (free, no credits). The full address is never
109
+ sent, only the domain:
110
+
111
+ ```js
112
+ await es.guard.recordEvents([
113
+ { domain: 'mailinator.com', verdict: 'disposable', action: 'deny', reasons: ['disposable_provider'], degraded: false, source: 'local' },
114
+ ]);
115
+ ```
98
116
 
99
117
  ## Credits and rate limits
100
118
 
@@ -115,7 +133,7 @@ Every failure throws a subclass of `EmailsherlockError`:
115
133
  | `ForbiddenError` | 403 | key lacks the endpoint's scope (`requiredScope`) |
116
134
  | `InsufficientCreditsError` | 402 | not enough credits (`creditsRequired`, `creditsRemaining`) |
117
135
  | `RateLimitError` | 429 | rate limit hit (`retryAfter`, `limit`, `remaining`, `reset`) |
118
- | `ValidationError` | 400 / 422 | the request body was rejected |
136
+ | `ValidationError` | 400 / 404 / 422 | the request was rejected, or the job was not found |
119
137
  | `ServiceUnavailableError` | 503 | verify engine unavailable (the credit is auto-refunded) |
120
138
 
121
139
  ```js
package/dist/client.d.ts CHANGED
@@ -1,4 +1,6 @@
1
- import type { VerifyResult, BatchResponse, RateLimit } from './types.js';
1
+ import { VerifyApi, GuardApi } from './generated/index.js';
2
+ import type { VerifyResultResponse, VerifyBatchResponse, VerifyJobResponse, AccountStatusResponse, GuardEventsRequest } from './generated/index.js';
3
+ import type { RateLimit } from './types.js';
2
4
  export interface ClientOptions {
3
5
  /** Your API key. Falls back to ES_KEY / EMAILSHERLOCK_API_KEY in the env. */
4
6
  apiKey?: string;
@@ -11,29 +13,41 @@ export interface ClientOptions {
11
13
  }
12
14
  /** Verify-endpoint methods, reached as `client.verify`. */
13
15
  export declare class VerifyResource {
14
- private readonly client;
15
- constructor(client: Emailsherlock);
16
+ private readonly api;
17
+ constructor(api: VerifyApi);
16
18
  /** Verify a single address. */
17
19
  single(params: {
18
20
  email: string;
19
- }): Promise<VerifyResult>;
20
- /** Verify up to 100 addresses in one call. */
21
+ }): Promise<VerifyResultResponse>;
22
+ /** Verify a batch of addresses in one call. */
21
23
  batch(params: {
22
24
  emails: string[];
23
- }): Promise<BatchResponse>;
25
+ }): Promise<VerifyBatchResponse>;
26
+ /** Submit a list of addresses for asynchronous verification. Poll with `getJob`. */
27
+ submitJob(params: {
28
+ emails: string[];
29
+ }): Promise<VerifyJobResponse>;
30
+ /** Read the status and results of a verification job. */
31
+ getJob(id: string): Promise<VerifyJobResponse>;
32
+ }
33
+ /** Email-Guard event methods, reached as `client.guard`. */
34
+ export declare class GuardResource {
35
+ private readonly api;
36
+ constructor(api: GuardApi);
37
+ /** Record a batch of Email-Guard decision events (free, no credits). */
38
+ recordEvents(events: GuardEventsRequest['events']): Promise<void>;
24
39
  }
25
40
  export declare class Emailsherlock {
26
41
  readonly verify: VerifyResource;
42
+ readonly guard: GuardResource;
27
43
  /** Credits left after the most recent request (from X-Credits-Remaining). */
28
44
  creditsRemaining: number | null;
29
45
  /** Rate-limit window after the most recent request (from X-RateLimit-*). */
30
46
  rateLimit: RateLimit;
31
- private readonly apiKey;
32
- private readonly baseUrl;
33
- private readonly timeoutMs;
34
- private readonly fetchImpl;
47
+ private readonly account;
35
48
  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>;
49
+ /** Read the credit balance and rate-limit status. Free: consumes no credits. */
50
+ credits(): Promise<AccountStatusResponse>;
51
+ private withTimeout;
38
52
  private captureMeta;
39
53
  }
package/dist/client.js CHANGED
@@ -1,5 +1,6 @@
1
+ import { Configuration, VerifyApi, AccountApi, GuardApi, } from './generated/index.js';
1
2
  import { VERSION } from './version.js';
2
- import { errorFromResponse, EmailsherlockError } from './errors.js';
3
+ import { EmailsherlockError, toEmailsherlockError } from './errors.js';
3
4
  const DEFAULT_BASE_URL = 'https://api.emailsherlock.com';
4
5
  function num(value) {
5
6
  if (value === null)
@@ -7,88 +8,107 @@ function num(value) {
7
8
  const n = Number(value);
8
9
  return Number.isFinite(n) ? n : null;
9
10
  }
10
- function safeParse(text) {
11
+ /** Run a generated-client call, mapping any failure to a named error. */
12
+ async function call(fn) {
11
13
  try {
12
- return JSON.parse(text);
14
+ return await fn();
13
15
  }
14
- catch {
15
- return null;
16
+ catch (err) {
17
+ throw await toEmailsherlockError(err);
16
18
  }
17
19
  }
18
20
  /** Verify-endpoint methods, reached as `client.verify`. */
19
21
  export class VerifyResource {
20
- client;
21
- constructor(client) {
22
- this.client = client;
22
+ api;
23
+ constructor(api) {
24
+ this.api = api;
23
25
  }
24
26
  /** Verify a single address. */
25
27
  single(params) {
26
- return this.client.request('/v1/verify/single', { email: params.email });
28
+ return call(() => this.api.verifySingle({ verifySingleRequest: { email: params.email } }));
27
29
  }
28
- /** Verify up to 100 addresses in one call. */
30
+ /** Verify a batch of addresses in one call. */
29
31
  batch(params) {
30
- return this.client.request('/v1/verify/batch', { emails: params.emails });
32
+ return call(() => this.api.verifyBatch({ verifyBatchRequest: { emails: params.emails } }));
33
+ }
34
+ /** Submit a list of addresses for asynchronous verification. Poll with `getJob`. */
35
+ submitJob(params) {
36
+ return call(() => this.api.submitVerifyJob({ verifyJobRequest: { emails: params.emails } }));
37
+ }
38
+ /** Read the status and results of a verification job. */
39
+ getJob(id) {
40
+ return call(() => this.api.getVerifyJob({ id }));
41
+ }
42
+ }
43
+ /** Email-Guard event methods, reached as `client.guard`. */
44
+ export class GuardResource {
45
+ api;
46
+ constructor(api) {
47
+ this.api = api;
48
+ }
49
+ /** Record a batch of Email-Guard decision events (free, no credits). */
50
+ recordEvents(events) {
51
+ return call(() => this.api.recordGuardEvents({ guardEventsRequest: { events } }));
31
52
  }
32
53
  }
33
54
  export class Emailsherlock {
34
55
  verify;
56
+ guard;
35
57
  /** Credits left after the most recent request (from X-Credits-Remaining). */
36
58
  creditsRemaining = null;
37
59
  /** Rate-limit window after the most recent request (from X-RateLimit-*). */
38
60
  rateLimit = { limit: null, remaining: null, reset: null };
39
- apiKey;
40
- baseUrl;
41
- timeoutMs;
42
- fetchImpl;
61
+ account;
43
62
  constructor(apiKey, options = {}) {
44
63
  const opts = typeof apiKey === 'string' ? { ...options, apiKey } : (apiKey ?? {});
45
64
  const key = opts.apiKey ?? process.env.ES_KEY ?? process.env.EMAILSHERLOCK_API_KEY;
46
65
  if (!key) {
47
66
  throw new EmailsherlockError('No API key provided. Pass it to the constructor or set ES_KEY.', { code: 'config_error' });
48
67
  }
49
- const fetchImpl = opts.fetch ?? globalThis.fetch;
50
- if (!fetchImpl) {
68
+ const baseFetch = opts.fetch ?? globalThis.fetch;
69
+ if (!baseFetch) {
51
70
  throw new EmailsherlockError('No fetch implementation available. Use Node 18+ or pass options.fetch.', { code: 'config_error' });
52
71
  }
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);
72
+ const timeoutMs = opts.timeoutMs ?? 30_000;
73
+ // Capture credit + rate-limit headers off every response, success or error.
74
+ const captureMeta = {
75
+ post: async (context) => {
76
+ this.captureMeta(context.response.headers);
77
+ },
78
+ };
79
+ const configuration = new Configuration({
80
+ basePath: (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
81
+ apiKey: key, // sets the X-API-Key header for ApiKeyAuth
82
+ headers: { 'User-Agent': `emailsherlock-node/${VERSION}` },
83
+ fetchApi: this.withTimeout(baseFetch, timeoutMs),
84
+ middleware: [captureMeta],
85
+ });
86
+ this.verify = new VerifyResource(new VerifyApi(configuration));
87
+ this.guard = new GuardResource(new GuardApi(configuration));
88
+ this.account = new AccountApi(configuration);
58
89
  }
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;
90
+ /** Read the credit balance and rate-limit status. Free: consumes no credits. */
91
+ credits() {
92
+ return call(() => this.account.getCredits());
93
+ }
94
+ withTimeout(baseFetch, timeoutMs) {
95
+ return async (input, init) => {
96
+ const controller = new AbortController();
97
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
98
+ const upstream = init?.signal;
99
+ if (upstream) {
100
+ if (upstream.aborted)
101
+ controller.abort();
102
+ else
103
+ upstream.addEventListener('abort', () => controller.abort(), { once: true });
104
+ }
105
+ try {
106
+ return await baseFetch(input, { ...init, signal: controller.signal });
107
+ }
108
+ finally {
109
+ clearTimeout(timer);
110
+ }
111
+ };
92
112
  }
93
113
  captureMeta(headers) {
94
114
  const credits = headers.get('X-Credits-Remaining');
package/dist/errors.d.ts CHANGED
@@ -1,10 +1,3 @@
1
- interface ApiErrorEnvelope {
2
- error?: {
3
- code?: string;
4
- message?: string;
5
- required_scope?: string;
6
- };
7
- }
8
1
  export interface ErrorOptions {
9
2
  status?: number;
10
3
  code?: string;
@@ -34,11 +27,16 @@ export declare class RateLimitError extends EmailsherlockError {
34
27
  remaining?: number | null;
35
28
  reset?: number | null;
36
29
  }
37
- /** 400 / 422 — the request body was rejected. */
30
+ /** 400 / 404 / 422 — the request was rejected. */
38
31
  export declare class ValidationError extends EmailsherlockError {
39
32
  }
40
33
  /** 503 — the verify engine could not answer; the credit was auto-refunded. */
41
34
  export declare class ServiceUnavailableError extends EmailsherlockError {
42
35
  }
43
- export declare function errorFromResponse(status: number, body: ApiErrorEnvelope | null, headers: Headers): EmailsherlockError;
44
- export {};
36
+ /**
37
+ * Map a thrown value from the generated runtime to one of our named errors.
38
+ * The runtime throws `ResponseError` (carries the `Response`) for non-2xx and
39
+ * `FetchError` for transport failures. Anything else is rewrapped so callers
40
+ * only ever catch `EmailsherlockError`.
41
+ */
42
+ export declare function toEmailsherlockError(err: unknown): Promise<EmailsherlockError>;
package/dist/errors.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { ResponseError, FetchError } from './generated/runtime.js';
1
2
  function num(value) {
2
3
  if (value === null)
3
4
  return null;
@@ -35,13 +36,21 @@ export class RateLimitError extends EmailsherlockError {
35
36
  remaining;
36
37
  reset;
37
38
  }
38
- /** 400 / 422 — the request body was rejected. */
39
+ /** 400 / 404 / 422 — the request was rejected. */
39
40
  export class ValidationError extends EmailsherlockError {
40
41
  }
41
42
  /** 503 — the verify engine could not answer; the credit was auto-refunded. */
42
43
  export class ServiceUnavailableError extends EmailsherlockError {
43
44
  }
44
- export function errorFromResponse(status, body, headers) {
45
+ async function safeJson(response) {
46
+ try {
47
+ return (await response.clone().json());
48
+ }
49
+ catch {
50
+ return null;
51
+ }
52
+ }
53
+ function fromStatus(status, body, headers) {
45
54
  const envelope = body?.error ?? {};
46
55
  const code = envelope.code;
47
56
  const message = envelope.message ?? `HTTP ${status}`;
@@ -69,6 +78,7 @@ export function errorFromResponse(status, body, headers) {
69
78
  return err;
70
79
  }
71
80
  case 400:
81
+ case 404:
72
82
  case 422:
73
83
  return new ValidationError(message, opts);
74
84
  case 503:
@@ -77,3 +87,28 @@ export function errorFromResponse(status, body, headers) {
77
87
  return new EmailsherlockError(message, opts);
78
88
  }
79
89
  }
90
+ /**
91
+ * Map a thrown value from the generated runtime to one of our named errors.
92
+ * The runtime throws `ResponseError` (carries the `Response`) for non-2xx and
93
+ * `FetchError` for transport failures. Anything else is rewrapped so callers
94
+ * only ever catch `EmailsherlockError`.
95
+ */
96
+ export async function toEmailsherlockError(err) {
97
+ if (err instanceof EmailsherlockError) {
98
+ return err;
99
+ }
100
+ if (err instanceof ResponseError) {
101
+ const { response } = err;
102
+ const body = await safeJson(response);
103
+ return fromStatus(response.status, body, response.headers);
104
+ }
105
+ if (err instanceof FetchError) {
106
+ const reason = err.cause instanceof Error ? err.cause.message : String(err.cause);
107
+ return new EmailsherlockError(`Request failed: ${reason}`, { code: 'network_error' });
108
+ }
109
+ if (err instanceof Error && err.name === 'AbortError') {
110
+ return new EmailsherlockError('Request timed out.', { code: 'timeout' });
111
+ }
112
+ const reason = err instanceof Error ? err.message : String(err);
113
+ return new EmailsherlockError(reason, { code: 'unknown_error' });
114
+ }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * EmailSherlock API
3
+ * Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
4
+ *
5
+ * The version of the OpenAPI document: 1.0.0
6
+ *
7
+ *
8
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
9
+ * https://openapi-generator.tech
10
+ * Do not edit the class manually.
11
+ */
12
+ import * as runtime from '../runtime.js';
13
+ import type { AccountStatusResponse } from '../models/index.js';
14
+ /**
15
+ *
16
+ */
17
+ export declare class AccountApi extends runtime.BaseAPI {
18
+ /**
19
+ * Creates request options for getCredits without sending the request
20
+ */
21
+ getCreditsRequestOpts(): Promise<runtime.RequestOpts>;
22
+ /**
23
+ * Read the credit balance and rate-limit status. Free: consumes no credits.
24
+ */
25
+ getCreditsRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AccountStatusResponse>>;
26
+ /**
27
+ * Read the credit balance and rate-limit status. Free: consumes no credits.
28
+ */
29
+ getCredits(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AccountStatusResponse>;
30
+ }
@@ -0,0 +1,51 @@
1
+ /* tslint:disable */
2
+ /* eslint-disable */
3
+ /**
4
+ * EmailSherlock API
5
+ * Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
6
+ *
7
+ * The version of the OpenAPI document: 1.0.0
8
+ *
9
+ *
10
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
11
+ * https://openapi-generator.tech
12
+ * Do not edit the class manually.
13
+ */
14
+ import * as runtime from '../runtime.js';
15
+ /**
16
+ *
17
+ */
18
+ export class AccountApi extends runtime.BaseAPI {
19
+ /**
20
+ * Creates request options for getCredits without sending the request
21
+ */
22
+ async getCreditsRequestOpts() {
23
+ const queryParameters = {};
24
+ const headerParameters = {};
25
+ if (this.configuration && this.configuration.apiKey) {
26
+ headerParameters["X-API-Key"] = await this.configuration.apiKey("X-API-Key"); // ApiKeyAuth authentication
27
+ }
28
+ let urlPath = `/v1/credits`;
29
+ return {
30
+ path: urlPath,
31
+ method: 'GET',
32
+ headers: headerParameters,
33
+ query: queryParameters,
34
+ };
35
+ }
36
+ /**
37
+ * Read the credit balance and rate-limit status. Free: consumes no credits.
38
+ */
39
+ async getCreditsRaw(initOverrides) {
40
+ const requestOptions = await this.getCreditsRequestOpts();
41
+ const response = await this.request(requestOptions, initOverrides);
42
+ return new runtime.JSONApiResponse(response);
43
+ }
44
+ /**
45
+ * Read the credit balance and rate-limit status. Free: consumes no credits.
46
+ */
47
+ async getCredits(initOverrides) {
48
+ const response = await this.getCreditsRaw(initOverrides);
49
+ return await response.value();
50
+ }
51
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * EmailSherlock API
3
+ * Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
4
+ *
5
+ * The version of the OpenAPI document: 1.0.0
6
+ *
7
+ *
8
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
9
+ * https://openapi-generator.tech
10
+ * Do not edit the class manually.
11
+ */
12
+ import * as runtime from '../runtime.js';
13
+ import type { GuardEventsRequest } from '../models/index.js';
14
+ export interface RecordGuardEventsRequest {
15
+ guardEventsRequest: GuardEventsRequest;
16
+ }
17
+ /**
18
+ *
19
+ */
20
+ export declare class GuardApi extends runtime.BaseAPI {
21
+ /**
22
+ * Creates request options for recordGuardEvents without sending the request
23
+ */
24
+ recordGuardEventsRequestOpts(requestParameters: RecordGuardEventsRequest): Promise<runtime.RequestOpts>;
25
+ /**
26
+ * Record a batch of Email-Guard decision events (free).
27
+ */
28
+ recordGuardEventsRaw(requestParameters: RecordGuardEventsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
29
+ /**
30
+ * Record a batch of Email-Guard decision events (free).
31
+ */
32
+ recordGuardEvents(requestParameters: RecordGuardEventsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;
33
+ }
@@ -0,0 +1,55 @@
1
+ /* tslint:disable */
2
+ /* eslint-disable */
3
+ /**
4
+ * EmailSherlock API
5
+ * Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
6
+ *
7
+ * The version of the OpenAPI document: 1.0.0
8
+ *
9
+ *
10
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
11
+ * https://openapi-generator.tech
12
+ * Do not edit the class manually.
13
+ */
14
+ import * as runtime from '../runtime.js';
15
+ /**
16
+ *
17
+ */
18
+ export class GuardApi extends runtime.BaseAPI {
19
+ /**
20
+ * Creates request options for recordGuardEvents without sending the request
21
+ */
22
+ async recordGuardEventsRequestOpts(requestParameters) {
23
+ if (requestParameters['guardEventsRequest'] == null) {
24
+ throw new runtime.RequiredError('guardEventsRequest', 'Required parameter "guardEventsRequest" was null or undefined when calling recordGuardEvents().');
25
+ }
26
+ const queryParameters = {};
27
+ const headerParameters = {};
28
+ headerParameters['Content-Type'] = 'application/json';
29
+ if (this.configuration && this.configuration.apiKey) {
30
+ headerParameters["X-API-Key"] = await this.configuration.apiKey("X-API-Key"); // ApiKeyAuth authentication
31
+ }
32
+ let urlPath = `/v1/guard/events`;
33
+ return {
34
+ path: urlPath,
35
+ method: 'POST',
36
+ headers: headerParameters,
37
+ query: queryParameters,
38
+ body: requestParameters['guardEventsRequest'],
39
+ };
40
+ }
41
+ /**
42
+ * Record a batch of Email-Guard decision events (free).
43
+ */
44
+ async recordGuardEventsRaw(requestParameters, initOverrides) {
45
+ const requestOptions = await this.recordGuardEventsRequestOpts(requestParameters);
46
+ const response = await this.request(requestOptions, initOverrides);
47
+ return new runtime.VoidApiResponse(response);
48
+ }
49
+ /**
50
+ * Record a batch of Email-Guard decision events (free).
51
+ */
52
+ async recordGuardEvents(requestParameters, initOverrides) {
53
+ await this.recordGuardEventsRaw(requestParameters, initOverrides);
54
+ }
55
+ }