@rocketverifier/sdk 1.0.0

package/README.md

@@ -0,0 +1,191 @@
+# @rocketverifier/sdk
+
+Official Node.js SDK for [RocketVerifier](https://rocketverifier.com) - Professional Email Verification API.
+
+## Features
+
+- ✅ **Full TypeScript Support** - Complete type definitions included
+- ⚡ **Lightweight** - Zero dependencies
+- 🔄 **Auto Retry** - Built-in retry logic with exponential backoff
+- 📦 **ESM & CommonJS** - Works with any module system
+- 🛡️ **Error Handling** - Typed error classes for easy handling
+
+## Installation
+
+```bash
+npm install @rocketverifier/sdk
+# or
+yarn add @rocketverifier/sdk
+# or
+pnpm add @rocketverifier/sdk
+```
+
+## Quick Start
+
+```typescript
+import RocketVerifier from '@rocketverifier/sdk';
+
+const rv = new RocketVerifier('rv_live_your_api_key');
+
+// Verify a single email
+const result = await rv.verify('user@example.com');
+
+console.log(result.status);   // 'deliverable'
+console.log(result.score);    // 95
+console.log(result.provider); // 'google.com'
+```
+
+## Single Email Verification
+
+```typescript
+const result = await rv.verify('user@example.com');
+
+// Result object
+{
+  email: 'user@example.com',
+  status: 'deliverable',      // 'deliverable' | 'undeliverable' | 'risky' | 'unknown'
+  reason: 'accepted_email',
+  score: 95,                  // 0-100 confidence score
+  domain: {
+    name: 'example.com',
+    acceptAll: false,         // Catch-all domain
+    disposable: false,        // Disposable email provider
+    free: false               // Free email provider
+  },
+  provider: 'google.com'      // Email service provider
+}
+```
+
+## Batch Verification
+
+```typescript
+// Create a batch job
+const job = await rv.batch.create({
+  name: 'My Email List',
+  emails: ['user1@example.com', 'user2@example.com', /* ... */],
+  webhookUrl: 'https://yoursite.com/webhook' // Optional
+});
+
+console.log(job.id); // 'job_abc123'
+
+// Check job status
+const status = await rv.batch.get(job.id);
+console.log(status.processedEmails); // 150
+
+// Wait for completion with progress updates
+const completed = await rv.batch.wait(job.id, {
+  pollInterval: 5000,
+  onProgress: (job) => {
+    console.log(`Progress: ${job.processedEmails}/${job.totalEmails}`);
+  }
+});
+
+// Download results
+const results = await rv.batch.download(job.id);
+console.log(results.length); // 1000
+```
+
+## Domain Check
+
+```typescript
+const domain = await rv.domain.check('example.com');
+
+console.log(domain.provider);    // 'google.com'
+console.log(domain.acceptAll);   // false
+console.log(domain.disposable);  // false
+console.log(domain.hasValidMx);  // true
+console.log(domain.mxRecords);   // [{ priority: 10, host: 'aspmx.l.google.com' }]
+```
+
+## Check Credits
+
+```typescript
+const credits = await rv.getCredits();
+
+console.log(credits.credits);       // 10000
+console.log(credits.usedToday);     // 150
+console.log(credits.usedThisMonth); // 2500
+```
+
+## Error Handling
+
+```typescript
+import RocketVerifier, {
+  AuthenticationError,
+  InsufficientCreditsError,
+  RateLimitError,
+  ValidationError
+} from '@rocketverifier/sdk';
+
+try {
+  const result = await rv.verify('user@example.com');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (error instanceof InsufficientCreditsError) {
+    console.log('Need more credits:', error.creditsRequired);
+  } else if (error instanceof RateLimitError) {
+    console.log('Rate limited. Retry after:', error.retryAfter, 'seconds');
+  } else if (error instanceof ValidationError) {
+    console.log('Invalid input:', error.message);
+  } else {
+    console.log('Unknown error:', error.message);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const rv = new RocketVerifier('rv_live_xxx', {
+  // Custom API URL (for testing)
+  baseUrl: 'https://api.rocketverifier.com',
+  
+  // Request timeout in ms (default: 30000)
+  timeout: 60000,
+  
+  // Max retry attempts (default: 3)
+  maxRetries: 5,
+  
+  // Custom headers
+  headers: {
+    'X-Custom-Header': 'value'
+  }
+});
+```
+
+## TypeScript
+
+All types are exported for TypeScript users:
+
+```typescript
+import RocketVerifier, {
+  VerificationResult,
+  BatchJob,
+  DomainCheckResult,
+  CreditBalance,
+  RocketVerifierConfig
+} from '@rocketverifier/sdk';
+
+// Fully typed responses
+const result: VerificationResult = await rv.verify('user@example.com');
+
+// Type-safe status checks
+if (result.status === 'deliverable') {
+  console.log('Email is valid!');
+}
+```
+
+## Requirements
+
+- Node.js 16.0.0 or higher
+
+## Links
+
+- [Documentation](https://docs.rocketverifier.com/sdks/nodejs)
+- [API Reference](https://docs.rocketverifier.com/api)
+- [GitHub](https://github.com/rocketverifier/sdk-node)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,256 @@
+/**
+ * RocketVerifier Node.js SDK
+ * Professional Email Verification
+ *
+ * @example
+ * ```typescript
+ * import RocketVerifier from '@rocketverifier/sdk';
+ *
+ * const rv = new RocketVerifier('rv_live_xxx');
+ * const result = await rv.verify('user@example.com');
+ * console.log(result.status); // 'deliverable'
+ * ```
+ */
+interface ApiErrorPayload {
+    error?: {
+        message?: string;
+        code?: string;
+        details?: Record<string, unknown> & {
+            creditsRequired?: number;
+            creditsAvailable?: number;
+        };
+    };
+    jobs?: Array<Record<string, unknown>>;
+}
+interface RocketVerifierConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API (default: https://api.rocketverifier.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+}
+interface DomainInfo {
+    /** Domain name */
+    name: string;
+    /** Whether domain accepts all emails (catch-all) */
+    acceptAll: boolean;
+    /** Whether domain is disposable */
+    disposable: boolean;
+    /** Whether domain is a free email provider */
+    free: boolean;
+}
+interface AccountInfo {
+    /** Whether email is role-based (admin@, info@, etc.) */
+    role: boolean;
+    /** Whether account is disabled */
+    disabled: boolean;
+    /** Whether mailbox is full */
+    fullMailbox: boolean | null;
+}
+interface DNSInfo {
+    /** DNS record type (usually "MX") */
+    type: string;
+    /** Primary MX record */
+    record: string;
+}
+interface VerificationResult {
+    /** The verified email address */
+    email: string;
+    /** Verification status: deliverable, undeliverable, risky, unknown */
+    status: 'deliverable' | 'undeliverable' | 'risky' | 'unknown';
+    /** Detailed reason for the status */
+    reason: string;
+    /** Domain information */
+    domain: DomainInfo;
+    /** Account information */
+    account?: AccountInfo;
+    /** DNS/MX information */
+    dns?: DNSInfo;
+    /** Email service provider (e.g., google.com) */
+    provider: string | null;
+    /** Confidence score (0-100) */
+    score: number;
+}
+interface BatchJob {
+    /** Unique job ID */
+    id: string;
+    /** Job name */
+    name: string | null;
+    /** Job status */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Total emails in job */
+    totalEmails: number;
+    /** Emails processed so far */
+    processedEmails: number;
+    /** Count of valid emails */
+    validCount: number;
+    /** Count of invalid emails */
+    invalidCount: number;
+    /** Count of risky emails */
+    riskyCount: number;
+    /** Count of unknown emails */
+    unknownCount: number;
+    /** Download URL (available when completed) */
+    downloadUrl?: string;
+    /** Job creation timestamp */
+    createdAt: string;
+    /** Job completion timestamp */
+    completedAt?: string;
+    /** Estimated completion time */
+    estimatedCompletion?: string;
+}
+interface BatchCreateOptions {
+    /** Job name (optional) */
+    name?: string;
+    /** List of emails to verify */
+    emails: string[];
+    /** Webhook URL for completion notification */
+    webhookUrl?: string;
+    /** Custom data to include in webhook */
+    callbackData?: Record<string, any>;
+}
+interface BatchWaitOptions {
+    /** Polling interval in milliseconds (default: 5000) */
+    pollInterval?: number;
+    /** Maximum wait time in milliseconds (default: 300000) */
+    timeout?: number;
+    /** Callback for progress updates */
+    onProgress?: (job: BatchJob) => void;
+}
+interface DomainCheckResult {
+    /** Domain name */
+    domain: string;
+    /** MX records */
+    mxRecords: Array<{
+        priority: number;
+        host: string;
+    }>;
+    /** Email service provider */
+    provider: string | null;
+    /** Whether domain accepts all emails */
+    acceptAll: boolean;
+    /** Whether domain is disposable */
+    disposable: boolean;
+    /** Whether domain has valid MX records */
+    hasValidMx: boolean;
+}
+interface CreditBalance {
+    /** Available credits */
+    credits: number;
+    /** Credits used today */
+    usedToday?: number;
+    /** Credits used this month */
+    usedThisMonth?: number;
+}
+declare class RocketVerifierError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: any | undefined);
+}
+declare class AuthenticationError extends RocketVerifierError {
+    constructor(message?: string);
+}
+declare class InsufficientCreditsError extends RocketVerifierError {
+    creditsRequired?: number | undefined;
+    creditsAvailable?: number | undefined;
+    constructor(message?: string, creditsRequired?: number | undefined, creditsAvailable?: number | undefined);
+}
+declare class RateLimitError extends RocketVerifierError {
+    retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+declare class ValidationError extends RocketVerifierError {
+    constructor(message: string, details?: any);
+}
+declare class RocketVerifier {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private maxRetries;
+    private headers;
+    /**
+     * Create a new RocketVerifier client
+     * @param apiKey - Your RocketVerifier API key
+     * @param config - Optional configuration
+     */
+    constructor(apiKey: string, config?: Partial<Omit<RocketVerifierConfig, 'apiKey'>>);
+    /**
+     * Make an authenticated API request
+     */
+    private request;
+    private sleep;
+    /**
+     * Verify a single email address
+     * @param email - Email address to verify
+     * @returns Verification result
+     * @example
+     * ```typescript
+     * const result = await rv.verify('user@example.com');
+     * if (result.status === 'deliverable') {
+     *   console.log('Email is valid!');
+     * }
+     * ```
+     */
+    verify(email: string): Promise<VerificationResult>;
+    /**
+     * Batch verification methods
+     */
+    batch: {
+        /**
+         * Create a new batch verification job
+         * @param options - Batch job options
+         * @returns Created job
+         */
+        create: (options: BatchCreateOptions) => Promise<BatchJob>;
+        /**
+         * Get the status of a batch job
+         * @param jobId - Job ID
+         * @returns Job status
+         */
+        get: (jobId: string) => Promise<BatchJob>;
+        /**
+         * Wait for a batch job to complete
+         * @param jobId - Job ID
+         * @param options - Wait options
+         * @returns Completed job
+         */
+        wait: (jobId: string, options?: BatchWaitOptions) => Promise<BatchJob>;
+        /**
+         * Download results for a completed batch job
+         * @param jobId - Job ID
+         * @returns Array of verification results
+         */
+        download: (jobId: string) => Promise<VerificationResult[]>;
+        /**
+         * List all batch jobs
+         * @param limit - Maximum jobs to return
+         * @param offset - Offset for pagination
+         * @returns List of jobs
+         */
+        list: (limit?: number, page?: number) => Promise<BatchJob[]>;
+    };
+    /**
+     * Domain check methods
+     */
+    domain: {
+        /**
+         * Check a domain's email configuration
+         * @param domain - Domain to check
+         * @returns Domain information
+         */
+        check: (domain: string) => Promise<DomainCheckResult>;
+    };
+    /**
+     * Get your credit balance
+     * @returns Credit balance information
+     */
+    getCredits(): Promise<CreditBalance>;
+}
+
+export { type AccountInfo, type ApiErrorPayload, AuthenticationError, type BatchCreateOptions, type BatchJob, type BatchWaitOptions, type CreditBalance, type DNSInfo, type DomainCheckResult, type DomainInfo, InsufficientCreditsError, RateLimitError, RocketVerifier, type RocketVerifierConfig, RocketVerifierError, ValidationError, type VerificationResult, RocketVerifier as default };

package/dist/index.d.ts

@@ -0,0 +1,256 @@
+/**
+ * RocketVerifier Node.js SDK
+ * Professional Email Verification
+ *
+ * @example
+ * ```typescript
+ * import RocketVerifier from '@rocketverifier/sdk';
+ *
+ * const rv = new RocketVerifier('rv_live_xxx');
+ * const result = await rv.verify('user@example.com');
+ * console.log(result.status); // 'deliverable'
+ * ```
+ */
+interface ApiErrorPayload {
+    error?: {
+        message?: string;
+        code?: string;
+        details?: Record<string, unknown> & {
+            creditsRequired?: number;
+            creditsAvailable?: number;
+        };
+    };
+    jobs?: Array<Record<string, unknown>>;
+}
+interface RocketVerifierConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API (default: https://api.rocketverifier.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+}
+interface DomainInfo {
+    /** Domain name */
+    name: string;
+    /** Whether domain accepts all emails (catch-all) */
+    acceptAll: boolean;
+    /** Whether domain is disposable */
+    disposable: boolean;
+    /** Whether domain is a free email provider */
+    free: boolean;
+}
+interface AccountInfo {
+    /** Whether email is role-based (admin@, info@, etc.) */
+    role: boolean;
+    /** Whether account is disabled */
+    disabled: boolean;
+    /** Whether mailbox is full */
+    fullMailbox: boolean | null;
+}
+interface DNSInfo {
+    /** DNS record type (usually "MX") */
+    type: string;
+    /** Primary MX record */
+    record: string;
+}
+interface VerificationResult {
+    /** The verified email address */
+    email: string;
+    /** Verification status: deliverable, undeliverable, risky, unknown */
+    status: 'deliverable' | 'undeliverable' | 'risky' | 'unknown';
+    /** Detailed reason for the status */
+    reason: string;
+    /** Domain information */
+    domain: DomainInfo;
+    /** Account information */
+    account?: AccountInfo;
+    /** DNS/MX information */
+    dns?: DNSInfo;
+    /** Email service provider (e.g., google.com) */
+    provider: string | null;
+    /** Confidence score (0-100) */
+    score: number;
+}
+interface BatchJob {
+    /** Unique job ID */
+    id: string;
+    /** Job name */
+    name: string | null;
+    /** Job status */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Total emails in job */
+    totalEmails: number;
+    /** Emails processed so far */
+    processedEmails: number;
+    /** Count of valid emails */
+    validCount: number;
+    /** Count of invalid emails */
+    invalidCount: number;
+    /** Count of risky emails */
+    riskyCount: number;
+    /** Count of unknown emails */
+    unknownCount: number;
+    /** Download URL (available when completed) */
+    downloadUrl?: string;
+    /** Job creation timestamp */
+    createdAt: string;
+    /** Job completion timestamp */
+    completedAt?: string;
+    /** Estimated completion time */
+    estimatedCompletion?: string;
+}
+interface BatchCreateOptions {
+    /** Job name (optional) */
+    name?: string;
+    /** List of emails to verify */
+    emails: string[];
+    /** Webhook URL for completion notification */
+    webhookUrl?: string;
+    /** Custom data to include in webhook */
+    callbackData?: Record<string, any>;
+}
+interface BatchWaitOptions {
+    /** Polling interval in milliseconds (default: 5000) */
+    pollInterval?: number;
+    /** Maximum wait time in milliseconds (default: 300000) */
+    timeout?: number;
+    /** Callback for progress updates */
+    onProgress?: (job: BatchJob) => void;
+}
+interface DomainCheckResult {
+    /** Domain name */
+    domain: string;
+    /** MX records */
+    mxRecords: Array<{
+        priority: number;
+        host: string;
+    }>;
+    /** Email service provider */
+    provider: string | null;
+    /** Whether domain accepts all emails */
+    acceptAll: boolean;
+    /** Whether domain is disposable */
+    disposable: boolean;
+    /** Whether domain has valid MX records */
+    hasValidMx: boolean;
+}
+interface CreditBalance {
+    /** Available credits */
+    credits: number;
+    /** Credits used today */
+    usedToday?: number;
+    /** Credits used this month */
+    usedThisMonth?: number;
+}
+declare class RocketVerifierError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: any | undefined);
+}
+declare class AuthenticationError extends RocketVerifierError {
+    constructor(message?: string);
+}
+declare class InsufficientCreditsError extends RocketVerifierError {
+    creditsRequired?: number | undefined;
+    creditsAvailable?: number | undefined;
+    constructor(message?: string, creditsRequired?: number | undefined, creditsAvailable?: number | undefined);
+}
+declare class RateLimitError extends RocketVerifierError {
+    retryAfter?: number | undefined;
+    constructor(message?: string, retryAfter?: number | undefined);
+}
+declare class ValidationError extends RocketVerifierError {
+    constructor(message: string, details?: any);
+}
+declare class RocketVerifier {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private maxRetries;
+    private headers;
+    /**
+     * Create a new RocketVerifier client
+     * @param apiKey - Your RocketVerifier API key
+     * @param config - Optional configuration
+     */
+    constructor(apiKey: string, config?: Partial<Omit<RocketVerifierConfig, 'apiKey'>>);
+    /**
+     * Make an authenticated API request
+     */
+    private request;
+    private sleep;
+    /**
+     * Verify a single email address
+     * @param email - Email address to verify
+     * @returns Verification result
+     * @example
+     * ```typescript
+     * const result = await rv.verify('user@example.com');
+     * if (result.status === 'deliverable') {
+     *   console.log('Email is valid!');
+     * }
+     * ```
+     */
+    verify(email: string): Promise<VerificationResult>;
+    /**
+     * Batch verification methods
+     */
+    batch: {
+        /**
+         * Create a new batch verification job
+         * @param options - Batch job options
+         * @returns Created job
+         */
+        create: (options: BatchCreateOptions) => Promise<BatchJob>;
+        /**
+         * Get the status of a batch job
+         * @param jobId - Job ID
+         * @returns Job status
+         */
+        get: (jobId: string) => Promise<BatchJob>;
+        /**
+         * Wait for a batch job to complete
+         * @param jobId - Job ID
+         * @param options - Wait options
+         * @returns Completed job
+         */
+        wait: (jobId: string, options?: BatchWaitOptions) => Promise<BatchJob>;
+        /**
+         * Download results for a completed batch job
+         * @param jobId - Job ID
+         * @returns Array of verification results
+         */
+        download: (jobId: string) => Promise<VerificationResult[]>;
+        /**
+         * List all batch jobs
+         * @param limit - Maximum jobs to return
+         * @param offset - Offset for pagination
+         * @returns List of jobs
+         */
+        list: (limit?: number, page?: number) => Promise<BatchJob[]>;
+    };
+    /**
+     * Domain check methods
+     */
+    domain: {
+        /**
+         * Check a domain's email configuration
+         * @param domain - Domain to check
+         * @returns Domain information
+         */
+        check: (domain: string) => Promise<DomainCheckResult>;
+    };
+    /**
+     * Get your credit balance
+     * @returns Credit balance information
+     */
+    getCredits(): Promise<CreditBalance>;
+}
+
+export { type AccountInfo, type ApiErrorPayload, AuthenticationError, type BatchCreateOptions, type BatchJob, type BatchWaitOptions, type CreditBalance, type DNSInfo, type DomainCheckResult, type DomainInfo, InsufficientCreditsError, RateLimitError, RocketVerifier, type RocketVerifierConfig, RocketVerifierError, ValidationError, type VerificationResult, RocketVerifier as default };

package/dist/index.js

@@ -0,0 +1,313 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  InsufficientCreditsError: () => InsufficientCreditsError,
+  RateLimitError: () => RateLimitError,
+  RocketVerifier: () => RocketVerifier,
+  RocketVerifierError: () => RocketVerifierError,
+  ValidationError: () => ValidationError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var RocketVerifierError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "RocketVerifierError";
+  }
+};
+var AuthenticationError = class extends RocketVerifierError {
+  constructor(message = "Invalid API key") {
+    super(message, "unauthorized", 401);
+    this.name = "AuthenticationError";
+  }
+};
+var InsufficientCreditsError = class extends RocketVerifierError {
+  constructor(message = "Insufficient credits", creditsRequired, creditsAvailable) {
+    super(message, "insufficient_credits", 402, { creditsRequired, creditsAvailable });
+    this.creditsRequired = creditsRequired;
+    this.creditsAvailable = creditsAvailable;
+    this.name = "InsufficientCreditsError";
+  }
+};
+var RateLimitError = class extends RocketVerifierError {
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message, "rate_limit_exceeded", 429, { retryAfter });
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+};
+var ValidationError = class extends RocketVerifierError {
+  constructor(message, details) {
+    super(message, "validation_error", 400, details);
+    this.name = "ValidationError";
+  }
+};
+var RocketVerifier = class {
+  /**
+   * Create a new RocketVerifier client
+   * @param apiKey - Your RocketVerifier API key
+   * @param config - Optional configuration
+   */
+  constructor(apiKey, config) {
+    // =========================================================================
+    // Batch Verification
+    // =========================================================================
+    /**
+     * Batch verification methods
+     */
+    this.batch = {
+      /**
+       * Create a new batch verification job
+       * @param options - Batch job options
+       * @returns Created job
+       */
+      create: async (options) => {
+        if (!options.emails || options.emails.length === 0) {
+          throw new ValidationError("At least one email is required");
+        }
+        return this.request("POST", "/v1/verify/bulk", {
+          emails: options.emails,
+          name: options.name
+        });
+      },
+      /**
+       * Get the status of a batch job
+       * @param jobId - Job ID
+       * @returns Job status
+       */
+      get: async (jobId) => {
+        const job = await this.request("GET", `/v1/jobs/${jobId}`);
+        return {
+          id: job.id,
+          name: job.name,
+          status: job.status,
+          totalEmails: job.total_emails ?? job.totalEmails,
+          processedEmails: job.processed_emails ?? job.processedEmails,
+          validCount: job.valid_count ?? job.validCount ?? 0,
+          invalidCount: job.invalid_count ?? job.invalidCount ?? 0,
+          riskyCount: job.risky_count ?? job.riskyCount ?? 0,
+          unknownCount: job.unknown_count ?? job.unknownCount ?? 0,
+          downloadUrl: job.download_url ?? job.downloadUrl,
+          createdAt: job.created_at ?? job.createdAt,
+          completedAt: job.completed_at ?? job.completedAt
+        };
+      },
+      /**
+       * Wait for a batch job to complete
+       * @param jobId - Job ID
+       * @param options - Wait options
+       * @returns Completed job
+       */
+      wait: async (jobId, options) => {
+        const pollInterval = options?.pollInterval || 5e3;
+        const timeout = options?.timeout || 3e5;
+        const startTime = Date.now();
+        while (true) {
+          const job = await this.batch.get(jobId);
+          if (options?.onProgress) {
+            options.onProgress(job);
+          }
+          if (job.status === "completed" || job.status === "failed") {
+            return job;
+          }
+          if (Date.now() - startTime > timeout) {
+            throw new RocketVerifierError("Timeout waiting for job", "timeout", 408);
+          }
+          await this.sleep(pollInterval);
+        }
+      },
+      /**
+       * Download results for a completed batch job
+       * @param jobId - Job ID
+       * @returns Array of verification results
+       */
+      download: async (jobId) => {
+        return this.request("GET", `/v1/jobs/${jobId}/download`);
+      },
+      /**
+       * List all batch jobs
+       * @param limit - Maximum jobs to return
+       * @param offset - Offset for pagination
+       * @returns List of jobs
+       */
+      list: async (limit = 10, page = 1) => {
+        const data = await this.request("GET", `/v1/jobs?limit=${limit}&page=${page}`);
+        return (data.jobs || []).map((job) => ({
+          id: job.id,
+          name: job.name,
+          status: job.status,
+          totalEmails: job.total_emails ?? job.totalEmails,
+          processedEmails: job.processed_emails ?? job.processedEmails,
+          validCount: job.valid_count ?? job.validCount ?? 0,
+          invalidCount: job.invalid_count ?? job.invalidCount ?? 0,
+          riskyCount: job.risky_count ?? job.riskyCount ?? 0,
+          unknownCount: job.unknown_count ?? job.unknownCount ?? 0,
+          downloadUrl: job.download_url ?? job.downloadUrl,
+          createdAt: job.created_at ?? job.createdAt,
+          completedAt: job.completed_at ?? job.completedAt
+        }));
+      }
+    };
+    // =========================================================================
+    // Domain Check
+    // =========================================================================
+    /**
+     * Domain check methods
+     */
+    this.domain = {
+      /**
+       * Check a domain's email configuration
+       * @param domain - Domain to check
+       * @returns Domain information
+       */
+      check: async (domain) => {
+        if (!domain) {
+          throw new ValidationError("Domain is required");
+        }
+        return this.request("POST", "/v1/domain/check", { domain });
+      }
+    };
+    if (!apiKey) {
+      throw new AuthenticationError("API key is required");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = config?.baseUrl || "https://api.rocketverifier.com";
+    this.timeout = config?.timeout || 3e4;
+    this.maxRetries = config?.maxRetries || 3;
+    this.headers = config?.headers || {};
+  }
+  /**
+   * Make an authenticated API request
+   */
+  async request(method, path, body, retries = 0) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "@rocketverifier/sdk/1.0.0",
+          ...this.headers
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const data = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        const error = data.error || {};
+        const message = error.message || `HTTP ${response.status}`;
+        const code = error.code || "unknown_error";
+        switch (response.status) {
+          case 401:
+            throw new AuthenticationError(message);
+          case 402:
+            throw new InsufficientCreditsError(
+              message,
+              error.details?.creditsRequired,
+              error.details?.creditsAvailable
+            );
+          case 429:
+            const retryAfter = parseInt(response.headers.get("Retry-After") || "60");
+            if (retries < this.maxRetries) {
+              await this.sleep(retryAfter * 1e3);
+              return this.request(method, path, body, retries + 1);
+            }
+            throw new RateLimitError(message, retryAfter);
+          case 400:
+            throw new ValidationError(message, error.details);
+          default:
+            throw new RocketVerifierError(message, code, response.status, error.details);
+        }
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof RocketVerifierError) {
+        throw error;
+      }
+      if (error.name === "AbortError") {
+        throw new RocketVerifierError("Request timeout", "timeout", 408);
+      }
+      if (retries < this.maxRetries) {
+        await this.sleep(1e3 * (retries + 1));
+        return this.request(method, path, body, retries + 1);
+      }
+      throw new RocketVerifierError(
+        error.message || "Network error",
+        "network_error",
+        0
+      );
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // =========================================================================
+  // Single Verification
+  // =========================================================================
+  /**
+   * Verify a single email address
+   * @param email - Email address to verify
+   * @returns Verification result
+   * @example
+   * ```typescript
+   * const result = await rv.verify('user@example.com');
+   * if (result.status === 'deliverable') {
+   *   console.log('Email is valid!');
+   * }
+   * ```
+   */
+  async verify(email) {
+    if (!email || !email.includes("@")) {
+      throw new ValidationError("Invalid email format");
+    }
+    return this.request("POST", "/v1/verify", { email });
+  }
+  // =========================================================================
+  // Credits
+  // =========================================================================
+  /**
+   * Get your credit balance
+   * @returns Credit balance information
+   */
+  async getCredits() {
+    return this.request("GET", "/v1/credits");
+  }
+};
+var index_default = RocketVerifier;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  InsufficientCreditsError,
+  RateLimitError,
+  RocketVerifier,
+  RocketVerifierError,
+  ValidationError
+});

package/dist/index.mjs

@@ -0,0 +1,283 @@
+// src/index.ts
+var RocketVerifierError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "RocketVerifierError";
+  }
+};
+var AuthenticationError = class extends RocketVerifierError {
+  constructor(message = "Invalid API key") {
+    super(message, "unauthorized", 401);
+    this.name = "AuthenticationError";
+  }
+};
+var InsufficientCreditsError = class extends RocketVerifierError {
+  constructor(message = "Insufficient credits", creditsRequired, creditsAvailable) {
+    super(message, "insufficient_credits", 402, { creditsRequired, creditsAvailable });
+    this.creditsRequired = creditsRequired;
+    this.creditsAvailable = creditsAvailable;
+    this.name = "InsufficientCreditsError";
+  }
+};
+var RateLimitError = class extends RocketVerifierError {
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message, "rate_limit_exceeded", 429, { retryAfter });
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+};
+var ValidationError = class extends RocketVerifierError {
+  constructor(message, details) {
+    super(message, "validation_error", 400, details);
+    this.name = "ValidationError";
+  }
+};
+var RocketVerifier = class {
+  /**
+   * Create a new RocketVerifier client
+   * @param apiKey - Your RocketVerifier API key
+   * @param config - Optional configuration
+   */
+  constructor(apiKey, config) {
+    // =========================================================================
+    // Batch Verification
+    // =========================================================================
+    /**
+     * Batch verification methods
+     */
+    this.batch = {
+      /**
+       * Create a new batch verification job
+       * @param options - Batch job options
+       * @returns Created job
+       */
+      create: async (options) => {
+        if (!options.emails || options.emails.length === 0) {
+          throw new ValidationError("At least one email is required");
+        }
+        return this.request("POST", "/v1/verify/bulk", {
+          emails: options.emails,
+          name: options.name
+        });
+      },
+      /**
+       * Get the status of a batch job
+       * @param jobId - Job ID
+       * @returns Job status
+       */
+      get: async (jobId) => {
+        const job = await this.request("GET", `/v1/jobs/${jobId}`);
+        return {
+          id: job.id,
+          name: job.name,
+          status: job.status,
+          totalEmails: job.total_emails ?? job.totalEmails,
+          processedEmails: job.processed_emails ?? job.processedEmails,
+          validCount: job.valid_count ?? job.validCount ?? 0,
+          invalidCount: job.invalid_count ?? job.invalidCount ?? 0,
+          riskyCount: job.risky_count ?? job.riskyCount ?? 0,
+          unknownCount: job.unknown_count ?? job.unknownCount ?? 0,
+          downloadUrl: job.download_url ?? job.downloadUrl,
+          createdAt: job.created_at ?? job.createdAt,
+          completedAt: job.completed_at ?? job.completedAt
+        };
+      },
+      /**
+       * Wait for a batch job to complete
+       * @param jobId - Job ID
+       * @param options - Wait options
+       * @returns Completed job
+       */
+      wait: async (jobId, options) => {
+        const pollInterval = options?.pollInterval || 5e3;
+        const timeout = options?.timeout || 3e5;
+        const startTime = Date.now();
+        while (true) {
+          const job = await this.batch.get(jobId);
+          if (options?.onProgress) {
+            options.onProgress(job);
+          }
+          if (job.status === "completed" || job.status === "failed") {
+            return job;
+          }
+          if (Date.now() - startTime > timeout) {
+            throw new RocketVerifierError("Timeout waiting for job", "timeout", 408);
+          }
+          await this.sleep(pollInterval);
+        }
+      },
+      /**
+       * Download results for a completed batch job
+       * @param jobId - Job ID
+       * @returns Array of verification results
+       */
+      download: async (jobId) => {
+        return this.request("GET", `/v1/jobs/${jobId}/download`);
+      },
+      /**
+       * List all batch jobs
+       * @param limit - Maximum jobs to return
+       * @param offset - Offset for pagination
+       * @returns List of jobs
+       */
+      list: async (limit = 10, page = 1) => {
+        const data = await this.request("GET", `/v1/jobs?limit=${limit}&page=${page}`);
+        return (data.jobs || []).map((job) => ({
+          id: job.id,
+          name: job.name,
+          status: job.status,
+          totalEmails: job.total_emails ?? job.totalEmails,
+          processedEmails: job.processed_emails ?? job.processedEmails,
+          validCount: job.valid_count ?? job.validCount ?? 0,
+          invalidCount: job.invalid_count ?? job.invalidCount ?? 0,
+          riskyCount: job.risky_count ?? job.riskyCount ?? 0,
+          unknownCount: job.unknown_count ?? job.unknownCount ?? 0,
+          downloadUrl: job.download_url ?? job.downloadUrl,
+          createdAt: job.created_at ?? job.createdAt,
+          completedAt: job.completed_at ?? job.completedAt
+        }));
+      }
+    };
+    // =========================================================================
+    // Domain Check
+    // =========================================================================
+    /**
+     * Domain check methods
+     */
+    this.domain = {
+      /**
+       * Check a domain's email configuration
+       * @param domain - Domain to check
+       * @returns Domain information
+       */
+      check: async (domain) => {
+        if (!domain) {
+          throw new ValidationError("Domain is required");
+        }
+        return this.request("POST", "/v1/domain/check", { domain });
+      }
+    };
+    if (!apiKey) {
+      throw new AuthenticationError("API key is required");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = config?.baseUrl || "https://api.rocketverifier.com";
+    this.timeout = config?.timeout || 3e4;
+    this.maxRetries = config?.maxRetries || 3;
+    this.headers = config?.headers || {};
+  }
+  /**
+   * Make an authenticated API request
+   */
+  async request(method, path, body, retries = 0) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "@rocketverifier/sdk/1.0.0",
+          ...this.headers
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const data = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        const error = data.error || {};
+        const message = error.message || `HTTP ${response.status}`;
+        const code = error.code || "unknown_error";
+        switch (response.status) {
+          case 401:
+            throw new AuthenticationError(message);
+          case 402:
+            throw new InsufficientCreditsError(
+              message,
+              error.details?.creditsRequired,
+              error.details?.creditsAvailable
+            );
+          case 429:
+            const retryAfter = parseInt(response.headers.get("Retry-After") || "60");
+            if (retries < this.maxRetries) {
+              await this.sleep(retryAfter * 1e3);
+              return this.request(method, path, body, retries + 1);
+            }
+            throw new RateLimitError(message, retryAfter);
+          case 400:
+            throw new ValidationError(message, error.details);
+          default:
+            throw new RocketVerifierError(message, code, response.status, error.details);
+        }
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof RocketVerifierError) {
+        throw error;
+      }
+      if (error.name === "AbortError") {
+        throw new RocketVerifierError("Request timeout", "timeout", 408);
+      }
+      if (retries < this.maxRetries) {
+        await this.sleep(1e3 * (retries + 1));
+        return this.request(method, path, body, retries + 1);
+      }
+      throw new RocketVerifierError(
+        error.message || "Network error",
+        "network_error",
+        0
+      );
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // =========================================================================
+  // Single Verification
+  // =========================================================================
+  /**
+   * Verify a single email address
+   * @param email - Email address to verify
+   * @returns Verification result
+   * @example
+   * ```typescript
+   * const result = await rv.verify('user@example.com');
+   * if (result.status === 'deliverable') {
+   *   console.log('Email is valid!');
+   * }
+   * ```
+   */
+  async verify(email) {
+    if (!email || !email.includes("@")) {
+      throw new ValidationError("Invalid email format");
+    }
+    return this.request("POST", "/v1/verify", { email });
+  }
+  // =========================================================================
+  // Credits
+  // =========================================================================
+  /**
+   * Get your credit balance
+   * @returns Credit balance information
+   */
+  async getCredits() {
+    return this.request("GET", "/v1/credits");
+  }
+};
+var index_default = RocketVerifier;
+export {
+  AuthenticationError,
+  InsufficientCreditsError,
+  RateLimitError,
+  RocketVerifier,
+  RocketVerifierError,
+  ValidationError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@rocketverifier/sdk",
+  "version": "1.0.0",
+  "description": "Official RocketVerifier Node.js SDK - Professional Email Verification",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "email",
+    "verification",
+    "validation",
+    "email-verification",
+    "email-validation",
+    "rocketverifier",
+    "smtp",
+    "mx",
+    "deliverability"
+  ],
+  "author": "RocketVerifier",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rocketverifier/sdk-node.git"
+  },
+  "homepage": "https://docs.rocketverifier.com/sdks/nodejs",
+  "bugs": {
+    "url": "https://github.com/rocketverifier/sdk-node/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}