@verifnow/sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,250 @@
+/**
+ * Validation rules exposed by the VerifNow API.
+ *
+ * Each maps to `POST /api/v1/validate/{rule}`.
+ */
+type ValidationRule = 'email' | 'phone' | 'iban' | 'vat' | 'nas' | 'ssn' | 'nif';
+declare const VALIDATION_RULES: readonly ValidationRule[];
+/**
+ * Depth of checks applied to a request, decided by the plan attached to the API key.
+ *
+ * `STANDARD` runs on the FREE and STARTER plans, `ADVANCED` on GROWTH, `PREMIUM` on PRO.
+ * Branch on this rather than on the plan name: it is the only value that tells you which
+ * signals are actually present in the response.
+ */
+type ValidationLevel = 'BASIC' | 'STANDARD' | 'ADVANCED' | 'PREMIUM';
+/** Categorical risk assessment. Returned from `ADVANCED` depth upward. */
+type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH';
+type Deliverability = 'DELIVERABLE' | 'RISKY' | 'UNDELIVERABLE' | 'UNKNOWN';
+/**
+ * Per-signal breakdown behind an email verdict.
+ *
+ * Fields are `undefined` when the applied level does not compute them — the last four require
+ * `ADVANCED` depth or higher. Check `ValidationResult.appliedLevel` before relying on one.
+ */
+interface EmailSignals {
+    /** The address matches the syntax pattern for the applied level. */
+    syntaxValid?: boolean;
+    /** The domain resolves and publishes MX (or fallback A) records. */
+    mxValid?: boolean;
+    /** A likely typo was found in the domain, e.g. `gmail.con`. */
+    typoDetected?: boolean;
+    /** The correction proposed when `typoDetected` is true. */
+    suggestedDomain?: string;
+    /** The domain belongs to a throwaway mailbox provider. */
+    disposable?: boolean;
+    /** The local part is a shared mailbox: `info@`, `admin@`, `noreply@`. */
+    roleBased?: boolean;
+    /** The domain is a consumer mailbox provider. Requires ADVANCED. */
+    freeProvider?: boolean;
+    /** Estimated age of the domain in days. Requires ADVANCED. */
+    domainAgeDays?: number;
+    /** Identified mail provider, e.g. `google`. Requires ADVANCED. */
+    mxProvider?: string;
+    /** Mail server quality between 0 and 1. Requires ADVANCED. */
+    mxQualityScore?: number;
+}
+/** Email-specific diagnostics. Absent when the applied level is `BASIC`. */
+interface EmailDetails {
+    signals?: EmailSignals;
+    /** Aggregated risk on a 0–100 scale, where 0 is the lowest risk. */
+    riskScore?: number;
+    /** Categorical risk. Requires ADVANCED depth or higher. */
+    riskLevel?: RiskLevel;
+    deliverability?: Deliverability;
+    /** The depth actually applied, echoed back by the API. */
+    appliedLevel?: ValidationLevel;
+}
+/** Outcome of a single validation call. */
+interface ValidationResult {
+    /** Whether the value passed every check the applied level ran. */
+    valid: boolean;
+    /** Human-readable explanation of the verdict. */
+    message?: string;
+    /** Canonical form of the input — `null` when the value is invalid. */
+    normalizedValue: string | null;
+    /** The value exactly as submitted. */
+    originalValue?: string;
+    /** Depth applied to this request. */
+    validationLevel?: ValidationLevel;
+    /** Present for email validations from `STANDARD` depth upward. */
+    emailDetails?: EmailDetails;
+    /** Quota state reported by the response headers. */
+    quota?: QuotaInfo;
+    /** The unmodified JSON body, for fields this SDK version does not model yet. */
+    raw: Record<string, unknown>;
+}
+/** Quota counters read from the `X-RateLimit-*` response headers. */
+interface QuotaInfo {
+    /** Validations included in the current billing period. */
+    limit?: number;
+    /** Validations left before overage or blocking. */
+    remaining?: number;
+    /** When the current period resets. */
+    resetAt?: Date;
+    /** True once you are past the included quota and into per-unit billing. */
+    overage?: boolean;
+}
+interface RetryOptions {
+    /**
+     * Retry attempts after the first failure. Defaults to 2, so up to 3 requests in total.
+     * Only connection failures, 429 and 5xx are retried — never a 400 or 401, which will not
+     * succeed on a second try.
+     */
+    attempts?: number;
+    /** Delay before the first retry, in ms. Doubles each attempt. Defaults to 200. */
+    backoffMs?: number;
+    /** Upper bound on a single backoff delay, in ms. Defaults to 2000. */
+    maxBackoffMs?: number;
+}
+interface VerifNowOptions {
+    /** API key created in the VerifNow dashboard. Sent as the `X-API-KEY` header. */
+    apiKey: string;
+    /** Override the API origin. Defaults to `https://api.verifnow.io`. */
+    baseUrl?: string;
+    /** Abort a single request after this many ms. Defaults to 5000. */
+    timeoutMs?: number;
+    /** Retry policy, or `false` to disable retries entirely. */
+    retry?: RetryOptions | false;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Replacement for the global `fetch`, for tests or a custom agent.
+     * Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+
+/** Per-call overrides. */
+interface RequestOptions {
+    /** Override the client timeout for this call. */
+    timeoutMs?: number;
+    /** Cancel the call from your own controller. Combined with the timeout. */
+    signal?: AbortSignal;
+}
+/**
+ * Client for the VerifNow validation API.
+ *
+ * @example
+ * ```ts
+ * import { VerifNow } from '@verifnow/sdk';
+ *
+ * const client = new VerifNow({ apiKey: process.env.VERIFNOW_API_KEY! });
+ * const result = await client.validateEmail('user@example.com');
+ *
+ * if (!result.valid) console.log(result.message);
+ * if (result.emailDetails?.signals?.typoDetected) {
+ *   console.log('Did you mean', result.emailDetails.signals.suggestedDomain);
+ * }
+ * ```
+ */
+declare class VerifNow {
+    #private;
+    constructor(options: VerifNowOptions);
+    /** Validate an email address: syntax, DNS/MX, typo, disposable, role-based, quality score. */
+    validateEmail(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a phone number in international format. */
+    validatePhone(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate an IBAN: country structure and check digits. */
+    validateIban(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a VAT number. */
+    validateVat(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a Canadian Social Insurance Number. */
+    validateNas(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a US Social Security Number. */
+    validateSsn(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a Spanish/Portuguese NIF. */
+    validateNif(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /**
+     * Validate a value against any rule.
+     *
+     * The typed helpers above call this. Use it directly when the rule is chosen at runtime.
+     */
+    validate(rule: ValidationRule, value: string, options?: RequestOptions): Promise<ValidationResult>;
+}
+
+/**
+ * Base class for every error this SDK throws.
+ *
+ * The SDK fails loudly on purpose. A validation client that swallows a network failure and
+ * reports `valid: true` turns an outage into silently accepted bad data, and the outage stays
+ * invisible until someone audits the database. Catch these and decide explicitly — accepting the
+ * input on failure is a reasonable choice, but it should be a choice.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const result = await client.validateEmail(input);
+ *   return result.valid;
+ * } catch (error) {
+ *   if (error instanceof VerifNowRateLimitError) throw error; // back-pressure, do not swallow
+ *   logger.warn({ error }, 'VerifNow unavailable, accepting input unverified');
+ *   return true;
+ * }
+ * ```
+ */
+declare class VerifNowError extends Error {
+    /** HTTP status, when the failure came back from the API rather than the network. */
+    readonly status?: number;
+    /** Correlation id from the `X-Request-Id` response header, useful in support requests. */
+    readonly requestId?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+/** The API key is missing, malformed, revoked, or not authorised for this endpoint (401/403). */
+declare class VerifNowAuthError extends VerifNowError {
+}
+/**
+ * The request was rejected as malformed (400).
+ *
+ * Retrying is pointless — the payload itself needs to change.
+ */
+declare class VerifNowRequestError extends VerifNowError {
+}
+/** The monthly quota or the concurrency limit was exceeded (429). */
+declare class VerifNowRateLimitError extends VerifNowError {
+    /** Quota counters from the response headers, when present. */
+    readonly quota?: QuotaInfo;
+    /** Seconds to wait before retrying, derived from `Retry-After` or `X-RateLimit-Reset`. */
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        requestId?: string;
+        cause?: unknown;
+        quota?: QuotaInfo;
+        retryAfterSeconds?: number;
+    });
+}
+/** The API failed to process the request (5xx). Retried automatically before surfacing. */
+declare class VerifNowServerError extends VerifNowError {
+}
+/**
+ * The API could not be reached at all: DNS failure, refused connection, TLS error, or the
+ * request exceeded `timeoutMs`.
+ *
+ * A wrong `baseUrl` surfaces here, which is why it names the URL it tried.
+ */
+declare class VerifNowConnectionError extends VerifNowError {
+    /** True when the failure was the client-side timeout rather than a transport error. */
+    readonly timedOut: boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        timedOut?: boolean;
+    });
+}
+/** The API returned a success status with a body this SDK could not parse. */
+declare class VerifNowResponseError extends VerifNowError {
+}
+
+/**
+ * SDK version, sent to the API as `X-VerifNow-SDK: node/<version>` so calls made through an
+ * official SDK can be told apart from hand-rolled integrations.
+ *
+ * Kept in sync with `package.json` by a test — bump both together.
+ */
+declare const VERSION = "1.0.0";
+
+export { type Deliverability, type EmailDetails, type EmailSignals, type QuotaInfo, type RequestOptions, type RetryOptions, type RiskLevel, VALIDATION_RULES, VERSION, type ValidationLevel, type ValidationResult, type ValidationRule, VerifNow, VerifNowAuthError, VerifNowConnectionError, VerifNowError, type VerifNowOptions, VerifNowRateLimitError, VerifNowRequestError, VerifNowResponseError, VerifNowServerError };

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Validation rules exposed by the VerifNow API.
+ *
+ * Each maps to `POST /api/v1/validate/{rule}`.
+ */
+type ValidationRule = 'email' | 'phone' | 'iban' | 'vat' | 'nas' | 'ssn' | 'nif';
+declare const VALIDATION_RULES: readonly ValidationRule[];
+/**
+ * Depth of checks applied to a request, decided by the plan attached to the API key.
+ *
+ * `STANDARD` runs on the FREE and STARTER plans, `ADVANCED` on GROWTH, `PREMIUM` on PRO.
+ * Branch on this rather than on the plan name: it is the only value that tells you which
+ * signals are actually present in the response.
+ */
+type ValidationLevel = 'BASIC' | 'STANDARD' | 'ADVANCED' | 'PREMIUM';
+/** Categorical risk assessment. Returned from `ADVANCED` depth upward. */
+type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH';
+type Deliverability = 'DELIVERABLE' | 'RISKY' | 'UNDELIVERABLE' | 'UNKNOWN';
+/**
+ * Per-signal breakdown behind an email verdict.
+ *
+ * Fields are `undefined` when the applied level does not compute them — the last four require
+ * `ADVANCED` depth or higher. Check `ValidationResult.appliedLevel` before relying on one.
+ */
+interface EmailSignals {
+    /** The address matches the syntax pattern for the applied level. */
+    syntaxValid?: boolean;
+    /** The domain resolves and publishes MX (or fallback A) records. */
+    mxValid?: boolean;
+    /** A likely typo was found in the domain, e.g. `gmail.con`. */
+    typoDetected?: boolean;
+    /** The correction proposed when `typoDetected` is true. */
+    suggestedDomain?: string;
+    /** The domain belongs to a throwaway mailbox provider. */
+    disposable?: boolean;
+    /** The local part is a shared mailbox: `info@`, `admin@`, `noreply@`. */
+    roleBased?: boolean;
+    /** The domain is a consumer mailbox provider. Requires ADVANCED. */
+    freeProvider?: boolean;
+    /** Estimated age of the domain in days. Requires ADVANCED. */
+    domainAgeDays?: number;
+    /** Identified mail provider, e.g. `google`. Requires ADVANCED. */
+    mxProvider?: string;
+    /** Mail server quality between 0 and 1. Requires ADVANCED. */
+    mxQualityScore?: number;
+}
+/** Email-specific diagnostics. Absent when the applied level is `BASIC`. */
+interface EmailDetails {
+    signals?: EmailSignals;
+    /** Aggregated risk on a 0–100 scale, where 0 is the lowest risk. */
+    riskScore?: number;
+    /** Categorical risk. Requires ADVANCED depth or higher. */
+    riskLevel?: RiskLevel;
+    deliverability?: Deliverability;
+    /** The depth actually applied, echoed back by the API. */
+    appliedLevel?: ValidationLevel;
+}
+/** Outcome of a single validation call. */
+interface ValidationResult {
+    /** Whether the value passed every check the applied level ran. */
+    valid: boolean;
+    /** Human-readable explanation of the verdict. */
+    message?: string;
+    /** Canonical form of the input — `null` when the value is invalid. */
+    normalizedValue: string | null;
+    /** The value exactly as submitted. */
+    originalValue?: string;
+    /** Depth applied to this request. */
+    validationLevel?: ValidationLevel;
+    /** Present for email validations from `STANDARD` depth upward. */
+    emailDetails?: EmailDetails;
+    /** Quota state reported by the response headers. */
+    quota?: QuotaInfo;
+    /** The unmodified JSON body, for fields this SDK version does not model yet. */
+    raw: Record<string, unknown>;
+}
+/** Quota counters read from the `X-RateLimit-*` response headers. */
+interface QuotaInfo {
+    /** Validations included in the current billing period. */
+    limit?: number;
+    /** Validations left before overage or blocking. */
+    remaining?: number;
+    /** When the current period resets. */
+    resetAt?: Date;
+    /** True once you are past the included quota and into per-unit billing. */
+    overage?: boolean;
+}
+interface RetryOptions {
+    /**
+     * Retry attempts after the first failure. Defaults to 2, so up to 3 requests in total.
+     * Only connection failures, 429 and 5xx are retried — never a 400 or 401, which will not
+     * succeed on a second try.
+     */
+    attempts?: number;
+    /** Delay before the first retry, in ms. Doubles each attempt. Defaults to 200. */
+    backoffMs?: number;
+    /** Upper bound on a single backoff delay, in ms. Defaults to 2000. */
+    maxBackoffMs?: number;
+}
+interface VerifNowOptions {
+    /** API key created in the VerifNow dashboard. Sent as the `X-API-KEY` header. */
+    apiKey: string;
+    /** Override the API origin. Defaults to `https://api.verifnow.io`. */
+    baseUrl?: string;
+    /** Abort a single request after this many ms. Defaults to 5000. */
+    timeoutMs?: number;
+    /** Retry policy, or `false` to disable retries entirely. */
+    retry?: RetryOptions | false;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Replacement for the global `fetch`, for tests or a custom agent.
+     * Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+
+/** Per-call overrides. */
+interface RequestOptions {
+    /** Override the client timeout for this call. */
+    timeoutMs?: number;
+    /** Cancel the call from your own controller. Combined with the timeout. */
+    signal?: AbortSignal;
+}
+/**
+ * Client for the VerifNow validation API.
+ *
+ * @example
+ * ```ts
+ * import { VerifNow } from '@verifnow/sdk';
+ *
+ * const client = new VerifNow({ apiKey: process.env.VERIFNOW_API_KEY! });
+ * const result = await client.validateEmail('user@example.com');
+ *
+ * if (!result.valid) console.log(result.message);
+ * if (result.emailDetails?.signals?.typoDetected) {
+ *   console.log('Did you mean', result.emailDetails.signals.suggestedDomain);
+ * }
+ * ```
+ */
+declare class VerifNow {
+    #private;
+    constructor(options: VerifNowOptions);
+    /** Validate an email address: syntax, DNS/MX, typo, disposable, role-based, quality score. */
+    validateEmail(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a phone number in international format. */
+    validatePhone(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate an IBAN: country structure and check digits. */
+    validateIban(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a VAT number. */
+    validateVat(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a Canadian Social Insurance Number. */
+    validateNas(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a US Social Security Number. */
+    validateSsn(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /** Validate a Spanish/Portuguese NIF. */
+    validateNif(value: string, options?: RequestOptions): Promise<ValidationResult>;
+    /**
+     * Validate a value against any rule.
+     *
+     * The typed helpers above call this. Use it directly when the rule is chosen at runtime.
+     */
+    validate(rule: ValidationRule, value: string, options?: RequestOptions): Promise<ValidationResult>;
+}
+
+/**
+ * Base class for every error this SDK throws.
+ *
+ * The SDK fails loudly on purpose. A validation client that swallows a network failure and
+ * reports `valid: true` turns an outage into silently accepted bad data, and the outage stays
+ * invisible until someone audits the database. Catch these and decide explicitly — accepting the
+ * input on failure is a reasonable choice, but it should be a choice.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const result = await client.validateEmail(input);
+ *   return result.valid;
+ * } catch (error) {
+ *   if (error instanceof VerifNowRateLimitError) throw error; // back-pressure, do not swallow
+ *   logger.warn({ error }, 'VerifNow unavailable, accepting input unverified');
+ *   return true;
+ * }
+ * ```
+ */
+declare class VerifNowError extends Error {
+    /** HTTP status, when the failure came back from the API rather than the network. */
+    readonly status?: number;
+    /** Correlation id from the `X-Request-Id` response header, useful in support requests. */
+    readonly requestId?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+/** The API key is missing, malformed, revoked, or not authorised for this endpoint (401/403). */
+declare class VerifNowAuthError extends VerifNowError {
+}
+/**
+ * The request was rejected as malformed (400).
+ *
+ * Retrying is pointless — the payload itself needs to change.
+ */
+declare class VerifNowRequestError extends VerifNowError {
+}
+/** The monthly quota or the concurrency limit was exceeded (429). */
+declare class VerifNowRateLimitError extends VerifNowError {
+    /** Quota counters from the response headers, when present. */
+    readonly quota?: QuotaInfo;
+    /** Seconds to wait before retrying, derived from `Retry-After` or `X-RateLimit-Reset`. */
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        requestId?: string;
+        cause?: unknown;
+        quota?: QuotaInfo;
+        retryAfterSeconds?: number;
+    });
+}
+/** The API failed to process the request (5xx). Retried automatically before surfacing. */
+declare class VerifNowServerError extends VerifNowError {
+}
+/**
+ * The API could not be reached at all: DNS failure, refused connection, TLS error, or the
+ * request exceeded `timeoutMs`.
+ *
+ * A wrong `baseUrl` surfaces here, which is why it names the URL it tried.
+ */
+declare class VerifNowConnectionError extends VerifNowError {
+    /** True when the failure was the client-side timeout rather than a transport error. */
+    readonly timedOut: boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        timedOut?: boolean;
+    });
+}
+/** The API returned a success status with a body this SDK could not parse. */
+declare class VerifNowResponseError extends VerifNowError {
+}
+
+/**
+ * SDK version, sent to the API as `X-VerifNow-SDK: node/<version>` so calls made through an
+ * official SDK can be told apart from hand-rolled integrations.
+ *
+ * Kept in sync with `package.json` by a test — bump both together.
+ */
+declare const VERSION = "1.0.0";
+
+export { type Deliverability, type EmailDetails, type EmailSignals, type QuotaInfo, type RequestOptions, type RetryOptions, type RiskLevel, VALIDATION_RULES, VERSION, type ValidationLevel, type ValidationResult, type ValidationRule, VerifNow, VerifNowAuthError, VerifNowConnectionError, VerifNowError, type VerifNowOptions, VerifNowRateLimitError, VerifNowRequestError, VerifNowResponseError, VerifNowServerError };