veripy-sdk 1.0.0

package/LICENSE.md

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Veripy
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# veripy-sdk
+
+The official Node.js wrapper for the Veripy Email Verification API.
+
+## Installation
+
+```bash
+npm install veripy-sdk
+```
+
+## Usage
+
+```typescript
+import VeripyClient from 'veripy-sdk';
+
+const client = new VeripyClient({
+  apiKey: 'vp_your_api_key_here'
+});
+
+async function run() {
+  const result = await client.verify('test@example.com');
+  console.log(result);
+  /**
+   * {
+   *   valid: true,
+   *   email: "test@example.com",
+   *   results: {
+   *     syntax: true,
+   *     disposable: false,
+   *     mx_records: true,
+   *     mailbox: true
+   *   },
+   *   score: 0.95,
+   *   timestamp: 1741512345678
+   * }
+   */
+}
+
+run();
+```

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+interface VerifyResult {
+    valid: boolean;
+    email: string;
+    results: {
+        syntax: boolean;
+        disposable: boolean;
+        mx_records: boolean;
+        mailbox: boolean;
+    };
+    score: number;
+    timestamp: number;
+}
+export interface VeripyConfig {
+    spamDetection?: boolean;
+    rateLimit?: boolean;
+}
+export declare class VeripyClient {
+    private url;
+    private apiKey;
+    private globalConfig;
+    private history;
+    private readonly SPAM_WINDOW_MS;
+    private readonly MAX_SIMILAR_REQUESTS;
+    constructor(options: {
+        url?: string;
+        apiKey: string;
+        config?: VeripyConfig;
+    });
+    /**
+     * Helper to detect if two emails are highly similar variations
+     * (e.g., test1@example.com and test2@example.com)
+     */
+    private isSimilar;
+    /**
+     * Helper for built in rate limiter (Token Bucket)
+     */
+    private tokens;
+    private lastRefill;
+    private readonly MAX_TOKENS;
+    private readonly REFILL_RATE_PER_MS;
+    private checkRateLimit;
+    /**
+     * Verifies an email address.
+     * @param email The email address to verify.
+     * @param config Optional configuration to override global settings.
+     * @returns A Promise resolving to the verification result.
+     */
+    verify(email: string, config?: VeripyConfig): Promise<VerifyResult>;
+}
+export default VeripyClient;

package/dist/index.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeripyClient = void 0;
+class VeripyClient {
+    url;
+    apiKey;
+    globalConfig;
+    // Local memory cache for spam detection
+    history = [];
+    SPAM_WINDOW_MS = 60000; // 1 minute window
+    MAX_SIMILAR_REQUESTS = 3; // Block after 3 similar variations
+    constructor(options) {
+        this.url =
+            options.url || "https://lovable-alpaca-951.eu-west-1.convex.site";
+        if (!options.apiKey) {
+            throw new Error("VeripyClient requires an apiKey.");
+        }
+        this.apiKey = options.apiKey;
+        this.globalConfig = {
+            spamDetection: options.config?.spamDetection ?? true,
+            rateLimit: options.config?.rateLimit ?? true,
+        };
+    }
+    /**
+     * Helper to detect if two emails are highly similar variations
+     * (e.g., test1@example.com and test2@example.com)
+     */
+    isSimilar(email1, email2) {
+        const [local1, domain1] = email1.toLowerCase().split("@");
+        const [local2, domain2] = email2.toLowerCase().split("@");
+        if (domain1 !== domain2)
+            return false;
+        // Strip trailing numbers from the local part (e.g. 'test12' -> 'test')
+        const base1 = local1.replace(/\d+$/, "");
+        const base2 = local2.replace(/\d+$/, "");
+        // Also catch "plus addressing" variations (e.g. user+1@gmail.com and user+2@gmail.com)
+        const plusBase1 = local1.split("+")[0];
+        const plusBase2 = local2.split("+")[0];
+        return base1 === base2 || plusBase1 === plusBase2;
+    }
+    /**
+     * Helper for built in rate limiter (Token Bucket)
+     */
+    tokens = 10; // default starting burst
+    lastRefill = Date.now();
+    MAX_TOKENS = 10;
+    REFILL_RATE_PER_MS = 10 / (60 * 1000); // 10 tokens per minute
+    checkRateLimit() {
+        const now = Date.now();
+        const timePassed = now - this.lastRefill;
+        // Refill tokens based on time passed
+        this.tokens = Math.min(this.MAX_TOKENS, this.tokens + timePassed * this.REFILL_RATE_PER_MS);
+        this.lastRefill = now;
+        if (this.tokens < 1) {
+            throw new Error("Veripy Error: Rate limit exceeded locally. Slow down your requests.");
+        }
+        this.tokens -= 1;
+    }
+    /**
+     * Verifies an email address.
+     * @param email The email address to verify.
+     * @param config Optional configuration to override global settings.
+     * @returns A Promise resolving to the verification result.
+     */
+    async verify(email, config) {
+        if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new Error("Veripy Error: Invalid email format provided to SDK.");
+        }
+        const activeConfig = { ...this.globalConfig, ...config };
+        const now = Date.now();
+        // 1. Local Rate Limiting
+        if (activeConfig.rateLimit) {
+            this.checkRateLimit();
+        }
+        // 2. Local Spam Detection
+        if (activeConfig.spamDetection) {
+            // Clean up history older than our window
+            this.history = this.history.filter((req) => now - req.timestamp < this.SPAM_WINDOW_MS);
+            // Check for spam behavior locally
+            const similarCount = this.history.filter((req) => this.isSimilar(req.email, email)).length;
+            if (similarCount >= this.MAX_SIMILAR_REQUESTS) {
+                throw new Error("Veripy Error: Spam behavior detected. Too many highly similar requests locally.");
+            }
+            // Add to local history
+            this.history.push({ email, timestamp: now });
+        }
+        const response = await fetch(`${this.url}/v1/verify`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey,
+            },
+            body: JSON.stringify({ email }),
+        });
+        if (!response.ok) {
+            const error = await response
+                .json()
+                .catch(() => ({ error: response.statusText }));
+            throw new Error(`Veripy API Error: ${response.status} - ${error.error || response.statusText}`);
+        }
+        return (await response.json());
+    }
+}
+exports.VeripyClient = VeripyClient;
+exports.default = VeripyClient;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "veripy-sdk",
+  "version": "1.0.0",
+  "description": "Email verification wrapper for Veripy",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "verification",
+    "email",
+    "veripy",
+    "spam"
+  ],
+  "author": "Richard Banguiz",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/veripy.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/your-org/veripy/tree/main/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/your-org/veripy/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.0"
+  }
+}