@veqen/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keyveve, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @veqen/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official JavaScript/TypeScript client for [Veqen](https://veqen-app.com). Catch disposable emails, typos, datacenter and Tor IPs, and VoIP numbers with one call. Zero dependencies; runs on Node 20+ and server runtimes with fetch and crypto.randomUUID. Keep API keys out of browser code.
+
+```bash
+npm install https://veqen-app.com/static/sdk/veqen-sdk-0.1.0.tgz
+```
+
+```javascript
+import { Veqen } from "@veqen/sdk";
+
+const veqen = new Veqen(); // reads VEQEN_API_KEY
+const { risk } = await veqen.signup({ email: "jane@mailinator.com", ip: "185.220.101.1" });
+
+if (risk.verdict === "refuse") {
+  // block, or ask for a different email
+}
+```
+
+Methods: `email()`, `emails()`, `ip()`, `phone()`, `domain()`, `signup()`, `account()`, `usage()`. Errors throw `VeqenError` with `.status`, `.type` and `.requestId`. 429 and 5xx responses are retried automatically.
+
+Docs: https://veqen-app.com/docs

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@veqen/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official client for the Veqen signup-check API: disposable emails, datacenter IPs, VoIP numbers and more.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": ["src"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["email validation", "disposable email", "fraud", "signup", "ip lookup", "phone validation", "vpn detection", "mcp"],
+  "homepage": "https://veqen-app.com/docs/sdks",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Keyveve/veqen-sdks.git",
+    "directory": "js"
+  },
+  "bugs": { "url": "https://github.com/Keyveve/veqen-sdks/issues" },
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,134 @@
+export type Verdict = "admit" | "review" | "refuse";
+
+export interface Reason {
+  code: string;
+  impact: number;
+  message: string;
+  source?: "email" | "ip" | "phone" | "signup" | null;
+}
+
+export interface Risk {
+  score: number;
+  level: "low" | "medium" | "high";
+  verdict: Verdict;
+  reasons: Reason[];
+}
+
+export interface DomainInfo {
+  exists: boolean;
+  accepts_mail: boolean | null;
+  mx: string[];
+  null_mx: boolean;
+  spf: boolean;
+  dmarc: boolean;
+  registered_at: string | null;
+  age_days: number | null;
+  registrar: string | null;
+}
+
+export interface EmailCheck {
+  email: string;
+  valid_syntax: boolean;
+  syntax_error?: string | null;
+  normalized?: string | null;
+  canonical?: string | null;
+  local_part?: string | null;
+  domain?: string | null;
+  disposable?: boolean | null;
+  free_provider?: boolean | null;
+  role_account?: boolean | null;
+  plus_addressed?: boolean | null;
+  did_you_mean?: string | null;
+  domain_info?: DomainInfo | null;
+  mailbox?: { checked: boolean; result: "deliverable" | "undeliverable" | "catch_all" | "unknown"; smtp_code?: number | null; reason?: string | null } | null;
+  risk: Risk;
+}
+
+export interface IpCheck {
+  ip: string;
+  valid: boolean;
+  version?: number | null;
+  type?: "public" | "private" | "loopback" | "link_local" | "multicast" | "reserved" | "special" | null;
+  location?: {
+    country_code: string | null;
+    country: string | null;
+    in_eu: boolean | null;
+    region: string | null;
+    city: string | null;
+    continent: string | null;
+    latitude: number | null;
+    longitude: number | null;
+  } | null;
+  network?: {
+    asn: number | null;
+    organization: string | null;
+    kind: "cloud" | "hosting" | "cdn" | "vpn_hosting" | "isp" | "unknown";
+    kind_label: string;
+    known_network: string | null;
+  } | null;
+  flags?: { hosting: boolean; vpn_likely: boolean; relay: boolean; tor: boolean } | null;
+  risk: Risk;
+}
+
+export interface PhoneCheck {
+  input: string;
+  valid: boolean;
+  possible: boolean;
+  error?: string | null;
+  e164?: string | null;
+  international?: string | null;
+  national?: string | null;
+  calling_code?: number | null;
+  country_code?: string | null;
+  country?: string | null;
+  location?: string | null;
+  line_type?: string | null;
+  line_type_label?: string | null;
+  carrier?: string | null;
+  time_zones: string[];
+  risk: Risk;
+}
+
+export interface DomainCheck extends Partial<DomainInfo> {
+  input: string;
+  valid: boolean;
+  domain?: string | null;
+  disposable?: boolean | null;
+  free_provider?: boolean | null;
+  risk: Risk;
+}
+
+export interface SignupCheck {
+  email: EmailCheck | null;
+  ip: IpCheck | null;
+  phone: PhoneCheck | null;
+  risk: Risk;
+}
+
+export interface VeqenOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  fetch?: typeof fetch;
+}
+
+export class VeqenError extends Error {
+  status: number;
+  type: string;
+  requestId: string | null;
+}
+
+export class Veqen {
+  constructor(options?: VeqenOptions);
+  email(email: string, options?: { verifyMailbox?: boolean; idempotencyKey?: string }): Promise<EmailCheck>;
+  emails(emails: string[], options?: { verifyMailbox?: boolean }): Promise<EmailCheck[]>;
+  ip(ip: string, options?: { idempotencyKey?: string }): Promise<IpCheck>;
+  phone(phone: string, options?: { country?: string; idempotencyKey?: string }): Promise<PhoneCheck>;
+  domain(domain: string, options?: { idempotencyKey?: string }): Promise<DomainCheck>;
+  signup(input: { email?: string; ip?: string; phone?: string; phoneCountry?: string; verifyMailbox?: boolean; idempotencyKey?: string }): Promise<SignupCheck>;
+  account(): Promise<{ email: string; balance: { free: number; paid: number; total: number }; free_monthly_credits: number; free_resets_at: string; costs: Record<string, number>; rate_limit_per_second: number }>;
+  usage(days?: number): Promise<{ days: { date: string; credits: number; calls: number; by_check: Record<string, number> }[]; total_credits: number; total_calls: number }>;
+}
+
+export default Veqen;

package/src/index.js

@@ -0,0 +1,118 @@
+// Official JavaScript/TypeScript client for the Veqen signup-check API. Works anywhere `fetch` exists.
+
+const DEFAULT_BASE_URL = "https://veqen-app.com";
+const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+const VERSION = "0.1.0";
+
+export class VeqenError extends Error {
+  constructor(status, type, message, requestId) {
+    super(`${status} ${type}: ${message}`);
+    this.name = "VeqenError";
+    this.status = status;
+    this.type = type;
+    this.requestId = requestId;
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const env = (name) => (typeof process !== "undefined" && process.env ? process.env[name] : undefined);
+
+export class Veqen {
+  constructor(options = {}) {
+    this.apiKey = options.apiKey ?? env("VEQEN_API_KEY");
+    if (!this.apiKey) throw new Error("Pass { apiKey } or set VEQEN_API_KEY.");
+    this.baseUrl = (options.baseUrl ?? env("VEQEN_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? 10000;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  email(email, { verifyMailbox = false, idempotencyKey } = {}) {
+    return this.#post("/v1/email/check", { email, verify_mailbox: verifyMailbox }, idempotencyKey);
+  }
+
+  async emails(emails, { verifyMailbox = false } = {}) {
+    const results = [];
+    for (let start = 0; start < emails.length; start += 100) {
+      const chunk = emails.slice(start, start + 100);
+      const data = await this.#post("/v1/email/batch", { emails: chunk, verify_mailbox: verifyMailbox });
+      results.push(...data.results);
+    }
+    return results;
+  }
+
+  ip(ip, { idempotencyKey } = {}) {
+    return this.#post("/v1/ip/check", { ip }, idempotencyKey);
+  }
+
+  phone(phone, { country, idempotencyKey } = {}) {
+    return this.#post("/v1/phone/check", { phone, country }, idempotencyKey);
+  }
+
+  domain(domain, { idempotencyKey } = {}) {
+    return this.#post("/v1/domain/check", { domain }, idempotencyKey);
+  }
+
+  signup({ email, ip, phone, phoneCountry, verifyMailbox = false, idempotencyKey } = {}) {
+    const body = { email, ip, phone, phone_country: phoneCountry, verify_mailbox: verifyMailbox };
+    for (const key of Object.keys(body)) if (body[key] === undefined || body[key] === null || body[key] === "") delete body[key];
+    return this.#post("/v1/signup/check", body, idempotencyKey);
+  }
+
+  account() {
+    return this.#request("GET", "/v1/account");
+  }
+
+  usage(days = 30) {
+    return this.#request("GET", `/v1/usage?days=${encodeURIComponent(days)}`);
+  }
+
+  #post(path, body, idempotencyKey) {
+    // One key per logical call, shared by all retries to prevent double charging.
+    return this.#request("POST", path, body, idempotencyKey ?? globalThis.crypto.randomUUID());
+  }
+
+  async #request(method, path, body, idempotencyKey) {
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json",
+      "User-Agent": `veqen-js/${VERSION}`,
+    };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+
+    for (let attempt = 0; ; attempt += 1) {
+      let response;
+      try {
+        response = await this.fetch(`${this.baseUrl}${path}`, {
+          method,
+          headers,
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: AbortSignal.timeout(this.timeoutMs),
+        });
+      } catch (error) {
+        if (attempt >= this.maxRetries) throw error;
+        await sleep(Math.min(250 * 2 ** (attempt + 1), 4000));
+        continue;
+      }
+      if (RETRY_STATUSES.has(response.status) && attempt < this.maxRetries) {
+        const retryAfter = Number(response.headers.get("Retry-After"));
+        await sleep(retryAfter > 0 ? retryAfter * 1000 : Math.min(250 * 2 ** (attempt + 1), 4000));
+        continue;
+      }
+      let data = null;
+      try {
+        data = await response.json();
+      } catch {
+        data = null;
+      }
+      if (!response.ok) {
+        const error = (data && data.error) || {};
+        throw new VeqenError(response.status, error.type || "http_error", error.message || response.statusText, response.headers.get("X-Request-Id"));
+      }
+      return data;
+    }
+  }
+}
+
+export default Veqen;