veripy-sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,40 +1,75 @@
-# 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();
-```
+# veripy-sdk
+
+The official Node.js wrapper for the Veripy Email Verification API.
+
+## Installation
+
+```bash
+npm install veripy-sdk
+```
+
+## Basic Usage
+
+```typescript
+import VeripyClient from 'veripy-sdk';
+
+const client = new VeripyClient({
+  apiKey: 'vp_your_api_key_here'
+});
+
+const result = await client.verify('test@example.com');
+console.log(result);
+```
+
+## Configuration
+
+You can configure local security features to prevent API abuse and save on credits.
+
+```typescript
+const client = new VeripyClient({
+  apiKey: 'vp_your_api_key_here',
+  config: {
+    rateLimit: true,     // Enable local token bucket rate limiting (Default: true)
+    spamDetection: true  // Enable local similar-email detection (Default: true)
+  }
+});
+```
+
+### Local Rate Limiting
+The SDK includes a built-in token bucket rate limiter. By default, it allows a burst of **10 requests** and refills at a rate of **10 requests per minute**. This helps prevent accidental loops or spikes from consuming your API quota.
+
+### Local Spam Detection
+The SDK monitors request patterns and blocks "highly similar" email variations (e.g., `user1@gmail.com`, `user2@gmail.com`) if more than **3 variations** are sent within a **1 minute window**.
+
+## Per-Call Overrides
+
+You can override the global configuration for specific calls if needed.
+
+```typescript
+// Bypass local checks for a specific verification
+const result = await client.verify('test@example.com', {
+  rateLimit: false,
+  spamDetection: false
+});
+```
+
+## Types
+
+### VerifyResult
+```typescript
+interface VerifyResult {
+  valid: boolean;
+  email: string;
+  results: {
+    syntax: boolean;
+    disposable: boolean;
+    mx_records: boolean;
+    mailbox: boolean;
+  };
+  score: number;    // 0 to 1
+  timestamp: number;
+}
+```
+
+## License
+ISC

package/dist/index.d.mts

@@ -0,0 +1,51 @@
+interface VerifyResult {
+    valid: boolean;
+    email: string;
+    results: {
+        syntax: boolean;
+        disposable: boolean;
+        mx_records: boolean;
+        mailbox: boolean;
+    };
+    score: number;
+    timestamp: number;
+}
+interface VeripyConfig {
+    spamDetection?: boolean;
+    rateLimit?: boolean;
+}
+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 { VeripyClient, type VeripyConfig, VeripyClient as default };

package/dist/index.d.ts

@@ -10,11 +10,11 @@ interface VerifyResult {
     score: number;
     timestamp: number;
 }
-export interface VeripyConfig {
+interface VeripyConfig {
     spamDetection?: boolean;
     rateLimit?: boolean;
 }
-export declare class VeripyClient {
+declare class VeripyClient {
     private url;
     private apiKey;
     private globalConfig;
@@ -47,4 +47,5 @@ export declare class VeripyClient {
      */
     verify(email: string, config?: VeripyConfig): Promise<VerifyResult>;
 }
-export default VeripyClient;
+
+export { VeripyClient, type VeripyConfig, VeripyClient as default };

package/dist/index.js

@@ -1,105 +1 @@
-"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;
+"use strict";var p=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var d=(s,t)=>{for(var e in t)p(s,e,{get:t[e],enumerable:!0})},g=(s,t,e,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of f(t))!u.call(s,i)&&i!==e&&p(s,i,{get:()=>t[i],enumerable:!(o=y(t,i))||o.enumerable});return s};var b=s=>g(p({},"__esModule",{value:!0}),s);var w={};d(w,{VeripyClient:()=>l,default:()=>v});module.exports=b(w);var l=class{url;apiKey;globalConfig;history=[];SPAM_WINDOW_MS=6e4;MAX_SIMILAR_REQUESTS=3;constructor(t){if(this.url=t.url||"https://lovable-alpaca-951.eu-west-1.convex.site",!t.apiKey)throw new Error("VeripyClient requires an apiKey.");this.apiKey=t.apiKey,this.globalConfig={spamDetection:t.config?.spamDetection??!0,rateLimit:t.config?.rateLimit??!0}}isSimilar(t,e){let[o,i]=t.toLowerCase().split("@"),[r,n]=e.toLowerCase().split("@");if(i!==n)return!1;let a=o.replace(/\d+$/,""),c=r.replace(/\d+$/,""),h=o.split("+")[0],m=r.split("+")[0];return a===c||h===m}tokens=10;lastRefill=Date.now();MAX_TOKENS=10;REFILL_RATE_PER_MS=10/(60*1e3);checkRateLimit(){let t=Date.now(),e=t-this.lastRefill;if(this.tokens=Math.min(this.MAX_TOKENS,this.tokens+e*this.REFILL_RATE_PER_MS),this.lastRefill=t,this.tokens<1)throw new Error("Veripy Error: Rate limit exceeded locally. Slow down your requests.");this.tokens-=1}async verify(t,e){if(!t||!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t))throw new Error("Veripy Error: Invalid email format provided to SDK.");let o={...this.globalConfig,...e},i=Date.now();if(o.rateLimit&&this.checkRateLimit(),o.spamDetection){if(this.history=this.history.filter(a=>i-a.timestamp<this.SPAM_WINDOW_MS),this.history.filter(a=>this.isSimilar(a.email,t)).length>=this.MAX_SIMILAR_REQUESTS)throw new Error("Veripy Error: Spam behavior detected. Too many highly similar requests locally.");this.history.push({email:t,timestamp:i})}let r=await fetch(`${this.url}/v1/verify`,{method:"POST",headers:{"Content-Type":"application/json","x-api-key":this.apiKey},body:JSON.stringify({email:t})});if(!r.ok){let n=await r.json().catch(()=>({error:r.statusText}));throw new Error(`Veripy API Error: ${r.status} - ${n.error||r.statusText}`)}return await r.json()}},v=l;0&&(module.exports={VeripyClient});

package/dist/index.mjs

@@ -0,0 +1 @@
+var n=class{url;apiKey;globalConfig;history=[];SPAM_WINDOW_MS=6e4;MAX_SIMILAR_REQUESTS=3;constructor(t){if(this.url=t.url||"https://lovable-alpaca-951.eu-west-1.convex.site",!t.apiKey)throw new Error("VeripyClient requires an apiKey.");this.apiKey=t.apiKey,this.globalConfig={spamDetection:t.config?.spamDetection??!0,rateLimit:t.config?.rateLimit??!0}}isSimilar(t,i){let[r,o]=t.toLowerCase().split("@"),[e,a]=i.toLowerCase().split("@");if(o!==a)return!1;let s=r.replace(/\d+$/,""),l=e.replace(/\d+$/,""),p=r.split("+")[0],c=e.split("+")[0];return s===l||p===c}tokens=10;lastRefill=Date.now();MAX_TOKENS=10;REFILL_RATE_PER_MS=10/(60*1e3);checkRateLimit(){let t=Date.now(),i=t-this.lastRefill;if(this.tokens=Math.min(this.MAX_TOKENS,this.tokens+i*this.REFILL_RATE_PER_MS),this.lastRefill=t,this.tokens<1)throw new Error("Veripy Error: Rate limit exceeded locally. Slow down your requests.");this.tokens-=1}async verify(t,i){if(!t||!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t))throw new Error("Veripy Error: Invalid email format provided to SDK.");let r={...this.globalConfig,...i},o=Date.now();if(r.rateLimit&&this.checkRateLimit(),r.spamDetection){if(this.history=this.history.filter(s=>o-s.timestamp<this.SPAM_WINDOW_MS),this.history.filter(s=>this.isSimilar(s.email,t)).length>=this.MAX_SIMILAR_REQUESTS)throw new Error("Veripy Error: Spam behavior detected. Too many highly similar requests locally.");this.history.push({email:t,timestamp:o})}let e=await fetch(`${this.url}/v1/verify`,{method:"POST",headers:{"Content-Type":"application/json","x-api-key":this.apiKey},body:JSON.stringify({email:t})});if(!e.ok){let a=await e.json().catch(()=>({error:e.statusText}));throw new Error(`Veripy API Error: ${e.status} - ${a.error||e.statusText}`)}return await e.json()}},m=n;export{n as VeripyClient,m as default};

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "veripy-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Email verification wrapper for Veripy",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
+    "build": "tsup src/index.ts --format cjs,esm --dts --minify --clean",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -32,12 +33,14 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
     }
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "tsup": "^8.5.1",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0"
   }
-}
+}