smartvalidation-api 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# smartvalidation-api
+
+Validate emails, phones & usernames with **helpful error messages** and **fix suggestions**.
+
+## Install
+
+```bash
+npm install smartvalidation-api
+```
+
+## Get Your API Key
+
+1. Go to [RapidAPI](https://rapidapi.com/ritualhere2/api/smart-validation)
+2. Click "Subscribe" (free tier available)
+3. Copy your API key
+
+## Quick Start
+
+```javascript
+const validate = require('smartvalidation-api')('YOUR_API_KEY');
+
+// Validate email
+const email = await validate.email('john@gmial.com');
+console.log(email);
+// {
+//   valid: false,
+//   reason: 'Domain appears to be misspelled (did you mean gmail.com?)',
+//   suggestion: 'john@gmail.com'
+// }
+
+// Validate phone
+const phone = await validate.phone('+14155551234');
+console.log(phone);
+// { valid: true, normalized: '+14155551234', type: 'mobile', country: 'US' }
+
+// Validate username
+const username = await validate.username('john_doe');
+console.log(username);
+// { valid: true, normalized: 'john_doe' }
+```
+
+## Examples
+
+### Check if valid (boolean)
+
+```javascript
+if (await validate.isValidEmail('test@gmail.com')) {
+  // Email is valid
+}
+
+if (await validate.isValidPhone('+14155551234')) {
+  // Phone is valid
+}
+
+if (await validate.isValidUsername('john_doe')) {
+  // Username is valid
+}
+```
+
+### Validate multiple fields at once
+
+```javascript
+const result = await validate.all({
+  email: 'test@gmail.com',
+  phone: '+14155551234',
+  username: 'john_doe'
+});
+
+console.log(result.email.valid);    // true
+console.log(result.phone.valid);    // true
+console.log(result.username.valid); // true
+```
+
+### Phone with country code
+
+```javascript
+// For local numbers, provide the country
+const phone = await validate.phone('6971234567', 'GR');
+// { valid: true, normalized: '+306971234567', country: 'GR' }
+```
+
+### Handle errors nicely
+
+```javascript
+const result = await validate.email(userInput);
+
+if (!result.valid) {
+  // Show the reason to the user
+  alert(result.reason);
+  
+  // Offer the suggestion if available
+  if (result.suggestion) {
+    const useIt = confirm(`Did you mean ${result.suggestion}?`);
+    if (useIt) {
+      userInput = result.suggestion;
+    }
+  }
+}
+```
+
+## React Example
+
+```jsx
+import { useState } from 'react';
+const validate = require('smart-validation')('YOUR_API_KEY');
+
+function SignupForm() {
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState('');
+  const [suggestion, setSuggestion] = useState('');
+
+  const checkEmail = async () => {
+    const result = await validate.email(email);
+    
+    if (result.valid) {
+      setError('');
+      setSuggestion('');
+    } else {
+      setError(result.reason);
+      setSuggestion(result.suggestion || '');
+    }
+  };
+
+  return (
+    <div>
+      <input 
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        onBlur={checkEmail}
+        placeholder="Email"
+      />
+      {error && <p style={{color: 'red'}}>{error}</p>}
+      {suggestion && (
+        <button onClick={() => setEmail(suggestion)}>
+          Use {suggestion}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+## Next.js Example
+
+```javascript
+// pages/api/validate.js
+const validate = require('smart-validation')(process.env.RAPIDAPI_KEY);
+
+export default async function handler(req, res) {
+  const { email, phone, username } = req.body;
+  
+  const result = await validate.all({ email, phone, username });
+  
+  res.json(result);
+}
+```
+
+## What You Get
+
+### Email Validation
+- Catches typos (gmial.com → gmail.com)
+- Blocks temporary/disposable emails
+- Returns normalized lowercase version
+
+### Phone Validation
+- Works with any format
+- Returns E.164 normalized format
+- Detects mobile vs landline
+- Supports 200+ countries
+
+### Username Validation
+- Checks length (3-30 chars)
+- Must start with a letter
+- No consecutive special characters
+- Suggests valid alternatives
+
+## API Response Format
+
+### Valid
+```json
+{
+  "valid": true,
+  "normalized": "john@gmail.com"
+}
+```
+
+### Invalid
+```json
+{
+  "valid": false,
+  "reason": "Domain appears to be misspelled",
+  "suggestion": "john@gmail.com"
+}
+```
+
+## Need Help?
+
+- [Full Documentation](https://rapidapi.com/ritualhere2/api/smart-validation)
+- [Get API Key](https://rapidapi.com/ritualhere2/api/smart-validation)

package/index.d.ts

@@ -0,0 +1,50 @@
+declare module 'smart-validation' {
+  interface EmailResult {
+    valid: boolean;
+    normalized?: string;
+    reason?: string;
+    suggestion?: string;
+    disposable?: boolean;
+  }
+
+  interface PhoneResult {
+    valid: boolean;
+    normalized?: string;
+    type?: 'mobile' | 'landline' | 'voip' | 'toll-free' | string;
+    country?: string;
+    reason?: string;
+  }
+
+  interface UsernameResult {
+    valid: boolean;
+    normalized?: string;
+    reason?: string;
+    suggestions?: string[];
+  }
+
+  interface AllFields {
+    email?: string;
+    phone?: string;
+    username?: string;
+    country?: string;
+  }
+
+  interface AllResults {
+    email?: EmailResult;
+    phone?: PhoneResult;
+    username?: UsernameResult;
+  }
+
+  interface Validator {
+    email(email: string): Promise<EmailResult>;
+    phone(phone: string, country?: string): Promise<PhoneResult>;
+    username(username: string): Promise<UsernameResult>;
+    all(fields: AllFields): Promise<AllResults>;
+    isValidEmail(email: string): Promise<boolean>;
+    isValidPhone(phone: string, country?: string): Promise<boolean>;
+    isValidUsername(username: string): Promise<boolean>;
+  }
+
+  function createValidator(apiKey: string): Validator;
+  export = createValidator;
+}

package/index.js

@@ -0,0 +1,141 @@
+/**
+ * Smart Validation - Simple validation with helpful errors
+ * 
+ * Quick Start:
+ *   const validate = require('smart-validation')('YOUR_API_KEY');
+ *   const result = await validate.email('test@gmail.com');
+ */
+
+const API_URL = 'https://smart-validation.p.rapidapi.com/validate';
+const API_HOST = 'smart-validation.p.rapidapi.com';
+
+/**
+ * Create a validator instance
+ * @param {string} apiKey - Your RapidAPI key
+ * @returns {Object} Validator with email, phone, username, and all methods
+ */
+function createValidator(apiKey) {
+  if (!apiKey) {
+    throw new Error('API key is required. Get one at: https://rapidapi.com/ritualhere2/api/smart-validation');
+  }
+
+  /**
+   * Make API request
+   */
+  async function request(body) {
+    const response = await fetch(API_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-RapidAPI-Key': apiKey,
+        'X-RapidAPI-Host': API_HOST
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.message || `API error: ${response.status}`);
+    }
+
+    return response.json();
+  }
+
+  return {
+    /**
+     * Validate an email address
+     * @param {string} email - Email to validate
+     * @returns {Promise<Object>} { valid, normalized, reason, suggestion, disposable }
+     * 
+     * @example
+     * const result = await validate.email('john@gmial.com');
+     * // { valid: false, reason: 'Domain misspelled', suggestion: 'john@gmail.com' }
+     */
+    async email(email) {
+      const result = await request({ email });
+      return result.email;
+    },
+
+    /**
+     * Validate a phone number
+     * @param {string} phone - Phone number to validate
+     * @param {string} [country] - ISO country code (US, GB, etc.)
+     * @returns {Promise<Object>} { valid, normalized, type, country, reason }
+     * 
+     * @example
+     * const result = await validate.phone('+14155551234');
+     * // { valid: true, normalized: '+14155551234', type: 'mobile', country: 'US' }
+     */
+    async phone(phone, country) {
+      const body = { phone };
+      if (country) body.country = country;
+      const result = await request(body);
+      return result.phone;
+    },
+
+    /**
+     * Validate a username
+     * @param {string} username - Username to validate
+     * @returns {Promise<Object>} { valid, normalized, reason, suggestions }
+     * 
+     * @example
+     * const result = await validate.username('123user');
+     * // { valid: false, reason: 'Must start with letter', suggestions: ['user123'] }
+     */
+    async username(username) {
+      const result = await request({ username });
+      return result.username;
+    },
+
+    /**
+     * Validate multiple fields at once
+     * @param {Object} fields - { email, phone, username, country }
+     * @returns {Promise<Object>} Results for each provided field
+     * 
+     * @example
+     * const result = await validate.all({
+     *   email: 'test@gmail.com',
+     *   phone: '+14155551234',
+     *   username: 'john_doe'
+     * });
+     */
+    async all(fields) {
+      return request(fields);
+    },
+
+    /**
+     * Quick check if email is valid (returns boolean)
+     * @param {string} email 
+     * @returns {Promise<boolean>}
+     */
+    async isValidEmail(email) {
+      const result = await request({ email });
+      return result.email.valid;
+    },
+
+    /**
+     * Quick check if phone is valid (returns boolean)
+     * @param {string} phone 
+     * @param {string} [country]
+     * @returns {Promise<boolean>}
+     */
+    async isValidPhone(phone, country) {
+      const body = { phone };
+      if (country) body.country = country;
+      const result = await request(body);
+      return result.phone.valid;
+    },
+
+    /**
+     * Quick check if username is valid (returns boolean)
+     * @param {string} username 
+     * @returns {Promise<boolean>}
+     */
+    async isValidUsername(username) {
+      const result = await request({ username });
+      return result.username.valid;
+    }
+  };
+}
+
+module.exports = createValidator;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "smartvalidation-api",
+  "version": "1.0.0",
+  "description": "Validate emails, phones & usernames with smart error messages and fix suggestions",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "validation",
+    "email",
+    "phone",
+    "username",
+    "form",
+    "validator"
+  ],
+  "author": "",
+  "license": "MIT",
+  "homepage": "https://rapidapi.com/ritualhere2/api/smart-validation",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}