@bernierllc/sender-identity-verification 1.0.0

package/__tests__/integration.real-api.test.ts

@@ -0,0 +1,295 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+/**
+ * Real API Integration Tests
+ *
+ * These tests use REAL API credentials and make REAL API calls to:
+ * - SendGrid for sender verification
+ * - Name.com for DNS validation
+ *
+ * Run with: npm run test:integration
+ *
+ * Prerequisites:
+ * - .env.test file with valid API keys
+ * - Access to bernierllc.com domain
+ */
+
+import * as dotenv from 'dotenv';
+import * as path from 'path';
+import { SendGridProvider } from '../src/providers/SendGridProvider';
+import { SenderIdentity, EmailProvider, SenderStatus } from '../src/types';
+
+// Load test environment variables
+dotenv.config({ path: path.join(__dirname, '..', '.env.test') });
+
+// Skip these tests if API keys are not configured OR if not explicitly enabled
+// Set RUN_INTEGRATION_TESTS=true to run these tests
+const SKIP_INTEGRATION_TESTS = !process.env.RUN_INTEGRATION_TESTS || !process.env.SENDGRID_API_KEY || !process.env.TESTING_DOMAIN;
+
+describe('Real API Integration Tests', () => {
+  if (SKIP_INTEGRATION_TESTS) {
+    it.skip('Skipping integration tests - API keys not configured', () => {});
+    return;
+  }
+
+  const testDomain = process.env.TESTING_DOMAIN!;
+  const testEmail = `test-${Date.now()}@${testDomain}`;
+
+  const mockSender: SenderIdentity = {
+    id: `test-${Date.now()}`,
+    email: testEmail,
+    name: 'Test Sender',
+    replyToEmail: testEmail,
+    replyToName: 'Test Reply',
+    domain: testDomain,
+    provider: EmailProvider.SENDGRID,
+    status: SenderStatus.PENDING,
+    isDefault: false,
+    isActive: true,
+    verificationAttempts: 0,
+    createdAt: new Date(),
+    updatedAt: new Date()
+  };
+
+  // Move provider to outer scope so it's accessible to all test suites
+  let provider: SendGridProvider;
+  let createdSenderId: string | null = null;
+
+  beforeAll(() => {
+    provider = new SendGridProvider(process.env.SENDGRID_API_KEY!);
+  });
+
+  describe('SendGrid Real API', () => {
+    afterAll(async () => {
+      // Cleanup: Delete the test sender from SendGrid
+      if (createdSenderId) {
+        try {
+          await fetch(`https://api.sendgrid.com/v3/verified_senders/${createdSenderId}`, {
+            method: 'DELETE',
+            headers: {
+              'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
+              'Content-Type': 'application/json'
+            }
+          });
+          console.log(`✅ Cleaned up SendGrid sender: ${createdSenderId}`);
+        } catch (error) {
+          console.warn(`⚠️  Failed to cleanup SendGrid sender: ${error}`);
+        }
+      }
+    });
+
+    it('should successfully create sender with real SendGrid API', async () => {
+      const result = await provider.verifySender(mockSender);
+
+      console.log('📤 SendGrid Response:', JSON.stringify(result, null, 2));
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+      expect(result.data?.providerId).toBeDefined();
+
+      // Store for cleanup
+      if (result.data?.providerId) {
+        createdSenderId = result.data.providerId;
+        console.log(`📝 Created SendGrid sender ID: ${createdSenderId}`);
+      }
+    }, 30000); // 30 second timeout for real API call
+
+    it('should handle invalid API key with real SendGrid API', async () => {
+      const invalidProvider = new SendGridProvider('invalid-key-12345');
+      const result = await invalidProvider.verifySender(mockSender);
+
+      console.log('🔒 Invalid Key Response:', JSON.stringify(result, null, 2));
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+      // SendGrid returns specific error messages for auth failures
+      expect(
+        result.error?.includes('authorization') ||
+        result.error?.includes('Unauthorized') ||
+        result.error?.includes('API')
+      ).toBe(true);
+    }, 30000);
+
+    it('should return actual SendGrid metadata', async () => {
+      const result = await provider.verifySender({
+        ...mockSender,
+        email: `test-metadata-${Date.now()}@${testDomain}`
+      });
+
+      if (result.success && result.data) {
+        console.log('📊 SendGrid Metadata:', JSON.stringify(result.data.metadata, null, 2));
+
+        expect(result.data.metadata).toBeDefined();
+        expect(typeof result.data.metadata).toBe('object');
+
+        // Store for cleanup if created
+        if (result.data.providerId && result.data.providerId !== createdSenderId) {
+          // Cleanup this one too
+          setTimeout(async () => {
+            try {
+              await fetch(`https://api.sendgrid.com/v3/verified_senders/${result.data!.providerId}`, {
+                method: 'DELETE',
+                headers: {
+                  'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
+                  'Content-Type': 'application/json'
+                }
+              });
+            } catch (e) {
+              // Ignore cleanup errors
+            }
+          }, 1000);
+        }
+      }
+    }, 30000);
+  });
+
+  describe('Domain Verification with Real DNS', () => {
+    it('should extract correct domain from real email', () => {
+      const email = `sender@${testDomain}`;
+      const parts = email.split('@');
+
+      expect(parts.length).toBe(2);
+      expect(parts[1]).toBe(testDomain);
+    });
+
+    it('should validate bernardllc.com is a real domain', async () => {
+      // Test DNS resolution using native DNS lookup
+      const response = await fetch(`https://dns.google/resolve?name=${testDomain}&type=MX`);
+      const data = await response.json();
+
+      console.log(`🌐 DNS Records for ${testDomain}:`, JSON.stringify(data, null, 2));
+
+      expect(response.ok).toBe(true);
+      expect(data).toBeDefined();
+      // Real domain should have some DNS records
+      expect(data.Status).toBeDefined();
+    }, 30000);
+  });
+
+  describe('Error Handling with Real APIs', () => {
+    it('should handle empty API key', async () => {
+      const emptyProvider = new SendGridProvider('');
+      const result = await emptyProvider.verifySender(mockSender);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('not configured');
+    });
+
+    it('should handle malformed email address', async () => {
+      const result = await provider.verifySender({
+        ...mockSender,
+        email: 'not-an-email'
+      });
+
+      // SendGrid should reject this
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        console.log('❌ Malformed Email Error:', result.error);
+      }
+    }, 30000);
+
+    it('should handle network timeout gracefully', async () => {
+      // Create a provider with a short timeout (simulated by using invalid endpoint)
+      const result = await provider.verifySender({
+        ...mockSender,
+        email: `timeout-test-${Date.now()}@${testDomain}`
+      });
+
+      // Should eventually complete (success or fail, but not hang)
+      expect(result).toBeDefined();
+      expect(typeof result.success).toBe('boolean');
+    }, 10000);
+  });
+
+  describe('Real-World Scenarios', () => {
+    it('should verify sender with real domain ownership check', async () => {
+      // This test demonstrates the full workflow:
+      // 1. Create sender in SendGrid
+      // 2. SendGrid sends verification email
+      // 3. Domain must be real and accessible
+
+      const uniqueEmail = `verification-${Date.now()}@${testDomain}`;
+      const result = await provider.verifySender({
+        ...mockSender,
+        email: uniqueEmail
+      });
+
+      console.log('🔍 Verification Flow Result:', JSON.stringify(result, null, 2));
+
+      // Should succeed in creating the verification request
+      expect(result).toBeDefined();
+
+      // If successful, cleanup
+      if (result.success && result.data?.providerId) {
+        setTimeout(async () => {
+          try {
+            await fetch(`https://api.sendgrid.com/v3/verified_senders/${result.data!.providerId}`, {
+              method: 'DELETE',
+              headers: {
+                'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
+                'Content-Type': 'application/json'
+              }
+            });
+          } catch (e) {
+            // Ignore cleanup errors
+          }
+        }, 1000);
+      }
+    }, 30000);
+
+    it('should handle multiple concurrent verification requests', async () => {
+      const senders = [
+        `concurrent-1-${Date.now()}@${testDomain}`,
+        `concurrent-2-${Date.now()}@${testDomain}`,
+        `concurrent-3-${Date.now()}@${testDomain}`
+      ];
+
+      const results = await Promise.all(
+        senders.map(email =>
+          provider.verifySender({
+            ...mockSender,
+            email
+          })
+        )
+      );
+
+      console.log('🔄 Concurrent Results:', results.map((r: typeof results[0]) => ({
+        success: r.success,
+        providerId: r.success ? r.data?.providerId : undefined,
+        error: !r.success ? r.error : undefined
+      })));
+
+      // All should complete (success or failure)
+      expect(results.length).toBe(3);
+      results.forEach((result: typeof results[0]) => {
+        expect(result).toBeDefined();
+        expect(typeof result.success).toBe('boolean');
+      });
+
+      // Cleanup any successful creations
+      setTimeout(async () => {
+        for (const result of results) {
+          if (result.success && result.data?.providerId) {
+            try {
+              await fetch(`https://api.sendgrid.com/v3/verified_senders/${result.data.providerId}`, {
+                method: 'DELETE',
+                headers: {
+                  'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
+                  'Content-Type': 'application/json'
+                }
+              });
+            } catch (e) {
+              // Ignore cleanup errors
+            }
+          }
+        }
+      }, 2000);
+    }, 60000); // 60 seconds for concurrent operations
+  });
+});

package/__tests__/providers.test.ts

@@ -0,0 +1,331 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { SendGridProvider } from '../src/providers/SendGridProvider';
+import { MailgunProvider } from '../src/providers/MailgunProvider';
+import { SESProvider } from '../src/providers/SESProvider';
+import { SMTPProvider } from '../src/providers/SMTPProvider';
+import { SenderIdentity, EmailProvider, SenderStatus } from '../src/types';
+import { createFetchMock } from './__mocks__/fetch-mock';
+
+describe('Provider Tests with HTTP Mocking', () => {
+  const mockSender: SenderIdentity = {
+    id: 'test-123',
+    email: 'test@example.com',
+    name: 'Test User',
+    replyToEmail: 'reply@example.com',
+    replyToName: 'Reply User',
+    domain: 'example.com',
+    provider: EmailProvider.SENDGRID,
+    status: SenderStatus.PENDING,
+    isDefault: false,
+    isActive: true,
+    verificationAttempts: 0,
+    createdAt: new Date(),
+    updatedAt: new Date()
+  };
+
+  let fetchMock: ReturnType<typeof createFetchMock>;
+  let originalFetch: typeof fetch;
+
+  beforeEach(() => {
+    fetchMock = createFetchMock();
+    originalFetch = global.fetch;
+    global.fetch = fetchMock.getFetchMock() as typeof fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    fetchMock.clear();
+  });
+
+  describe('SendGridProvider', () => {
+    describe('Success Cases', () => {
+      it('should successfully verify sender with valid API key', async () => {
+        const provider = new SendGridProvider('test-api-key');
+
+        fetchMock.mockSuccess(
+          'https://api.sendgrid.com/v3/verified_senders',
+          {
+            id: 'sendgrid-123',
+            from_email: 'test@example.com',
+            verified: false,
+            nickname: 'Test User'
+          }
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(true);
+        expect(result.data).toBeDefined();
+        expect(result.data?.providerId).toBe('sendgrid-123');
+        expect(result.data?.metadata).toBeDefined();
+
+        const history = fetchMock.getCallHistory();
+        expect(history).toHaveLength(1);
+        expect(history[0].url).toBe('https://api.sendgrid.com/v3/verified_senders');
+        expect(history[0].method).toBe('POST');
+      });
+
+      it('should include sender details in request', async () => {
+        const provider = new SendGridProvider('test-api-key');
+
+        fetchMock.mockSuccess(
+          'https://api.sendgrid.com/v3/verified_senders',
+          { id: 'sendgrid-456', verified: false }
+        );
+
+        await provider.verifySender(mockSender);
+
+        const history = fetchMock.getCallHistory();
+        const requestBody = JSON.parse(history[0].body || '{}');
+
+        expect(requestBody.nickname).toBe('Test User');
+        expect(requestBody.from_email).toBe('test@example.com');
+        expect(requestBody.from_name).toBe('Test User');
+        expect(requestBody.reply_to).toBe('reply@example.com');
+        expect(requestBody.reply_to_name).toBe('Reply User');
+      });
+    });
+
+    describe('Error Cases', () => {
+      it('should fail without API key', async () => {
+        const provider = new SendGridProvider('');
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toContain('API key');
+      });
+
+      it('should handle 401 Unauthorized error', async () => {
+        const provider = new SendGridProvider('invalid-key');
+
+        fetchMock.mockError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          401,
+          {
+            errors: [{ message: 'Unauthorized - Invalid API key' }]
+          }
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('Unauthorized - Invalid API key');
+      });
+
+      it('should handle 403 Forbidden error', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          403,
+          {
+            errors: [{ message: 'Forbidden - Insufficient permissions' }]
+          }
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('Forbidden - Insufficient permissions');
+      });
+
+      it('should handle 404 Not Found error', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          404,
+          {
+            errors: [{ message: 'Resource not found' }]
+          }
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('Resource not found');
+      });
+
+      it('should handle 429 Rate Limit error', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          429,
+          {
+            errors: [{ message: 'Rate limit exceeded' }]
+          }
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('Rate limit exceeded');
+      });
+
+      it('should handle 500 Internal Server Error', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          500,
+          {
+            errors: [{ message: 'Internal server error' }]
+          }
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('Internal server error');
+      });
+
+      it('should handle network errors', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockNetworkError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          'Connection timeout'
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('Connection timeout');
+      });
+
+      it('should handle connection refused', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockNetworkError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          'Connection refused'
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('Connection refused');
+      });
+
+      it('should handle malformed response', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockError(
+          'https://api.sendgrid.com/v3/verified_senders',
+          400,
+          {} // Missing errors array
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBe('SendGrid verification failed');
+        expect(result.errors).toContain('SendGrid API error');
+      });
+
+      it('should handle response without ID', async () => {
+        const provider = new SendGridProvider('test-key');
+
+        fetchMock.mockSuccess(
+          'https://api.sendgrid.com/v3/verified_senders',
+          {
+            // Missing id field
+            verified: false
+          }
+        );
+
+        const result = await provider.verifySender(mockSender);
+
+        expect(result.success).toBe(true);
+        expect(result.data?.providerId).toBe('');
+      });
+    });
+  });
+
+  describe('MailgunProvider', () => {
+    it('should succeed without API key (domain-only verification)', async () => {
+      const provider = new MailgunProvider('');
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+      expect(result.data?.note).toContain('Mailgun does not require');
+    });
+
+    it('should succeed with API key', async () => {
+      const provider = new MailgunProvider('test-key');
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+    });
+
+    it('should note domain-level verification', async () => {
+      const provider = new MailgunProvider('mg-api-key');
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data?.note).toContain('individual sender verification');
+    });
+  });
+
+  describe('SESProvider', () => {
+    it('should succeed without credentials (stub implementation)', async () => {
+      const provider = new SESProvider('', '', '');
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+      expect(result.data?.note).toContain('SES verification stubbed');
+    });
+
+    it('should succeed with credentials', async () => {
+      const provider = new SESProvider('AKIAIOSFODNN7EXAMPLE', 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY', 'us-east-1');
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+    });
+
+    it('should note pending AWS SDK integration', async () => {
+      const provider = new SESProvider('key', 'secret', 'us-west-2');
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data?.note).toContain('AWS SDK integration pending');
+    });
+  });
+
+  describe('SMTPProvider', () => {
+    it('should always succeed (no verification required)', async () => {
+      const provider = new SMTPProvider();
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+    });
+
+    it('should note SMTP does not require verification', async () => {
+      const provider = new SMTPProvider();
+      const result = await provider.verifySender(mockSender);
+
+      expect(result.success).toBe(true);
+      expect(result.data?.note).toContain('SMTP does not require');
+    });
+  });
+});