@bernierllc/sender-identity-verification 1.0.0

package/dist/config.js

@@ -0,0 +1,38 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfigFromEnv = loadConfigFromEnv;
+/**
+ * Load configuration from environment variables
+ */
+function loadConfigFromEnv(overrides = {}) {
+    const config = {
+        verificationBaseUrl: process.env.SENDER_VERIFICATION_BASE_URL || overrides.verificationBaseUrl || '',
+        verificationFromEmail: process.env.SENDER_VERIFICATION_FROM_EMAIL || overrides.verificationFromEmail || 'noreply@example.com',
+        verificationFromName: process.env.SENDER_VERIFICATION_FROM_NAME || overrides.verificationFromName || 'Email Verification',
+        sendgridApiKey: process.env.SENDGRID_API_KEY || overrides.sendgridApiKey,
+        mailgunApiKey: process.env.MAILGUN_API_KEY || overrides.mailgunApiKey,
+        sesAccessKey: process.env.AWS_SES_ACCESS_KEY || overrides.sesAccessKey,
+        sesSecretKey: process.env.AWS_SES_SECRET_KEY || overrides.sesSecretKey,
+        sesRegion: process.env.AWS_SES_REGION || overrides.sesRegion || 'us-east-1',
+        databaseUrl: process.env.DATABASE_URL || overrides.databaseUrl,
+        emailSenderConfig: overrides.emailSenderConfig || {},
+        domainVerificationConfig: overrides.domainVerificationConfig || {},
+        retryConfig: overrides.retryConfig
+    };
+    // Log configuration (without sensitive data)
+    console.log('⚙️ Sender Identity Verification Configuration:');
+    console.log(`   └── Verification Base URL: ${config.verificationBaseUrl || '(not set)'}`);
+    console.log(`   └── From Email: ${config.verificationFromEmail}`);
+    console.log(`   └── SendGrid: ${config.sendgridApiKey ? '***configured***' : '(not set)'}`);
+    console.log(`   └── Mailgun: ${config.mailgunApiKey ? '***configured***' : '(not set)'}`);
+    console.log(`   └── SES: ${config.sesAccessKey ? '***configured***' : '(not set)'}`);
+    console.log(`   └── Database: ${config.databaseUrl ? '***configured***' : '(not set)'}`);
+    return config;
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import { SenderIdentityResult } from './types.js';
+/**
+ * Sender error codes
+ */
+export declare enum SenderErrorCode {
+    SENDER_NOT_FOUND = "SENDER_NOT_FOUND",
+    SENDER_ALREADY_EXISTS = "SENDER_ALREADY_EXISTS",
+    SENDER_LOCKED = "SENDER_LOCKED",
+    VERIFICATION_EXPIRED = "VERIFICATION_EXPIRED",
+    VERIFICATION_FAILED = "VERIFICATION_FAILED",
+    DOMAIN_NOT_VERIFIED = "DOMAIN_NOT_VERIFIED",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    INVALID_EMAIL = "INVALID_EMAIL",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+}
+/**
+ * Custom error class for sender verification errors
+ */
+export declare class SenderVerificationError extends Error {
+    code: SenderErrorCode;
+    details?: unknown | undefined;
+    constructor(message: string, code: SenderErrorCode, details?: unknown | undefined);
+}
+/**
+ * Error handling wrapper
+ */
+export declare function handleSenderError(error: unknown): SenderIdentityResult<never>;

package/dist/errors.js

@@ -0,0 +1,61 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SenderVerificationError = exports.SenderErrorCode = void 0;
+exports.handleSenderError = handleSenderError;
+/**
+ * Sender error codes
+ */
+var SenderErrorCode;
+(function (SenderErrorCode) {
+    SenderErrorCode["SENDER_NOT_FOUND"] = "SENDER_NOT_FOUND";
+    SenderErrorCode["SENDER_ALREADY_EXISTS"] = "SENDER_ALREADY_EXISTS";
+    SenderErrorCode["SENDER_LOCKED"] = "SENDER_LOCKED";
+    SenderErrorCode["VERIFICATION_EXPIRED"] = "VERIFICATION_EXPIRED";
+    SenderErrorCode["VERIFICATION_FAILED"] = "VERIFICATION_FAILED";
+    SenderErrorCode["DOMAIN_NOT_VERIFIED"] = "DOMAIN_NOT_VERIFIED";
+    SenderErrorCode["PROVIDER_ERROR"] = "PROVIDER_ERROR";
+    SenderErrorCode["INVALID_EMAIL"] = "INVALID_EMAIL";
+    SenderErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+})(SenderErrorCode || (exports.SenderErrorCode = SenderErrorCode = {}));
+/**
+ * Custom error class for sender verification errors
+ */
+class SenderVerificationError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'SenderVerificationError';
+        Object.setPrototypeOf(this, SenderVerificationError.prototype);
+    }
+}
+exports.SenderVerificationError = SenderVerificationError;
+/**
+ * Error handling wrapper
+ */
+function handleSenderError(error) {
+    if (error instanceof SenderVerificationError) {
+        return {
+            success: false,
+            error: error.message,
+            errors: [error.code]
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+    return {
+        success: false,
+        error: 'Unknown error occurred'
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { SenderIdentityVerification } from './SenderIdentityVerification.js';
+export { SenderIdentityConfig, loadConfigFromEnv } from './config.js';
+export { SenderVerificationError, SenderErrorCode, handleSenderError } from './errors.js';
+export { SenderIdentity, SenderStatus, EmailProvider, CreateSenderInput, UpdateSenderInput, VerificationResult, ComplianceCheckResult, ListSendersOptions, SenderIdentityResult, DomainVerificationStatus, IEmailDomainVerification } from './types.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailProvider = exports.SenderStatus = exports.handleSenderError = exports.SenderErrorCode = exports.SenderVerificationError = exports.loadConfigFromEnv = exports.SenderIdentityVerification = void 0;
+var SenderIdentityVerification_js_1 = require("./SenderIdentityVerification.js");
+Object.defineProperty(exports, "SenderIdentityVerification", { enumerable: true, get: function () { return SenderIdentityVerification_js_1.SenderIdentityVerification; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "loadConfigFromEnv", { enumerable: true, get: function () { return config_js_1.loadConfigFromEnv; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "SenderVerificationError", { enumerable: true, get: function () { return errors_js_1.SenderVerificationError; } });
+Object.defineProperty(exports, "SenderErrorCode", { enumerable: true, get: function () { return errors_js_1.SenderErrorCode; } });
+Object.defineProperty(exports, "handleSenderError", { enumerable: true, get: function () { return errors_js_1.handleSenderError; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "SenderStatus", { enumerable: true, get: function () { return types_js_1.SenderStatus; } });
+Object.defineProperty(exports, "EmailProvider", { enumerable: true, get: function () { return types_js_1.EmailProvider; } });

package/dist/providers/MailgunProvider.d.ts

@@ -0,0 +1,13 @@
+import { SenderIdentity, SenderIdentityResult } from '../types.js';
+/**
+ * Mailgun provider for sender verification
+ * Note: Mailgun doesn't have sender-level verification, only domain verification
+ */
+export declare class MailgunProvider {
+    constructor(_apiKey: string);
+    /**
+     * Verify sender with Mailgun
+     * Mailgun only verifies domains, not individual senders
+     */
+    verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>>;
+}

package/dist/providers/MailgunProvider.js

@@ -0,0 +1,35 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MailgunProvider = void 0;
+/**
+ * Mailgun provider for sender verification
+ * Note: Mailgun doesn't have sender-level verification, only domain verification
+ */
+class MailgunProvider {
+    constructor(_apiKey) {
+        // apiKey parameter reserved for future Mailgun API integration
+        void _apiKey;
+    }
+    /**
+     * Verify sender with Mailgun
+     * Mailgun only verifies domains, not individual senders
+     */
+    async verifySender(_sender) {
+        // Mailgun doesn't require individual sender verification
+        // Domain verification is handled by @bernierllc/email-domain-verification
+        return {
+            success: true,
+            data: {
+                note: 'Mailgun does not require individual sender verification'
+            }
+        };
+    }
+}
+exports.MailgunProvider = MailgunProvider;

package/dist/providers/SESProvider.d.ts

@@ -0,0 +1,12 @@
+import { SenderIdentity, SenderIdentityResult } from '../types.js';
+/**
+ * AWS SES provider for sender verification
+ */
+export declare class SESProvider {
+    constructor(_accessKey: string, _secretKey: string, _region: string);
+    /**
+     * Verify sender with AWS SES
+     * TODO: Implement AWS SDK integration for SES VerifyEmailIdentity
+     */
+    verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>>;
+}

package/dist/providers/SESProvider.js

@@ -0,0 +1,47 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESProvider = void 0;
+/**
+ * AWS SES provider for sender verification
+ */
+class SESProvider {
+    constructor(_accessKey, _secretKey, _region) {
+        // Parameters reserved for future AWS SDK integration
+        void _accessKey;
+        void _secretKey;
+        void _region;
+    }
+    /**
+     * Verify sender with AWS SES
+     * TODO: Implement AWS SDK integration for SES VerifyEmailIdentity
+     */
+    async verifySender(_sender) {
+        try {
+            // TODO: Call SES VerifyEmailIdentity API
+            // For now, return success (stub implementation)
+            // Real implementation would use AWS SDK:
+            // const ses = new SES({ region: this.region, credentials: {...} });
+            // await ses.verifyEmailIdentity({ EmailAddress: sender.email });
+            return {
+                success: true,
+                data: {
+                    note: 'SES verification stubbed - AWS SDK integration pending'
+                }
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'SES verification failed'
+            };
+        }
+    }
+}
+exports.SESProvider = SESProvider;

package/dist/providers/SMTPProvider.d.ts

@@ -0,0 +1,12 @@
+import { SenderIdentity, SenderIdentityResult } from '../types.js';
+/**
+ * SMTP provider for sender verification
+ * Note: SMTP doesn't require provider-level verification
+ */
+export declare class SMTPProvider {
+    /**
+     * Verify sender with SMTP
+     * SMTP doesn't require provider verification - just email validation
+     */
+    verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>>;
+}

package/dist/providers/SMTPProvider.js

@@ -0,0 +1,30 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SMTPProvider = void 0;
+/**
+ * SMTP provider for sender verification
+ * Note: SMTP doesn't require provider-level verification
+ */
+class SMTPProvider {
+    /**
+     * Verify sender with SMTP
+     * SMTP doesn't require provider verification - just email validation
+     */
+    async verifySender(_sender) {
+        // SMTP doesn't require provider-level verification
+        return {
+            success: true,
+            data: {
+                note: 'SMTP does not require provider-level verification'
+            }
+        };
+    }
+}
+exports.SMTPProvider = SMTPProvider;

package/dist/providers/SendGridProvider.d.ts

@@ -0,0 +1,19 @@
+import { SenderIdentity, SenderIdentityResult } from '../types.js';
+/**
+ * SendGrid provider for sender verification
+ */
+export declare class SendGridProvider {
+    private apiKey;
+    constructor(apiKey: string);
+    /**
+     * Verify sender with SendGrid
+     */
+    verifySender(sender: SenderIdentity): Promise<SenderIdentityResult<{
+        providerId: string;
+        metadata: Record<string, unknown>;
+    }>>;
+    /**
+     * Make SendGrid API request
+     */
+    private sendGridRequest;
+}

package/dist/providers/SendGridProvider.js

@@ -0,0 +1,98 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendGridProvider = void 0;
+/**
+ * SendGrid provider for sender verification
+ */
+class SendGridProvider {
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /**
+     * Verify sender with SendGrid
+     */
+    async verifySender(sender) {
+        try {
+            if (!this.apiKey) {
+                return {
+                    success: false,
+                    error: 'SendGrid API key not configured'
+                };
+            }
+            // Create verified sender in SendGrid
+            const response = await this.sendGridRequest('POST', '/verified_senders', {
+                nickname: sender.name,
+                from_email: sender.email,
+                from_name: sender.name,
+                reply_to: sender.replyToEmail,
+                reply_to_name: sender.replyToName,
+                address: '123 Main St',
+                city: 'Anytown',
+                state: 'CA', // Must be 2-character state code per SendGrid API requirements
+                zip: '12345',
+                country: 'US'
+            });
+            if (!response.success) {
+                return {
+                    success: false,
+                    error: 'SendGrid verification failed',
+                    errors: [response.error || 'Unknown SendGrid error']
+                };
+            }
+            return {
+                success: true,
+                data: {
+                    providerId: response.data?.id || '',
+                    metadata: response.data || {}
+                }
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'SendGrid verification failed'
+            };
+        }
+    }
+    /**
+     * Make SendGrid API request
+     */
+    async sendGridRequest(method, path, body) {
+        try {
+            const response = await fetch(`https://api.sendgrid.com/v3${path}`, {
+                method,
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json'
+                },
+                body: body ? JSON.stringify(body) : undefined
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    error: data.errors?.[0]?.message || 'SendGrid API error',
+                    errors: data.errors?.map((e) => e.message)
+                };
+            }
+            return {
+                success: true,
+                data: data
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'SendGrid request failed'
+            };
+        }
+    }
+}
+exports.SendGridProvider = SendGridProvider;

package/dist/templates/verification-email.d.ts

@@ -0,0 +1,9 @@
+import { SenderIdentity } from '../types.js';
+/**
+ * Build HTML verification email
+ */
+export declare function buildVerificationEmailHtml(sender: SenderIdentity, verificationUrl: string): string;
+/**
+ * Build plain text verification email
+ */
+export declare function buildVerificationEmailText(sender: SenderIdentity, verificationUrl: string): string;

package/dist/templates/verification-email.js

@@ -0,0 +1,67 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVerificationEmailHtml = buildVerificationEmailHtml;
+exports.buildVerificationEmailText = buildVerificationEmailText;
+/**
+ * Build HTML verification email
+ */
+function buildVerificationEmailHtml(sender, verificationUrl) {
+    return `
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <style>
+        body { font-family: Arial, sans-serif; line-height: 1.6; color: #333; }
+        .container { max-width: 600px; margin: 0 auto; padding: 20px; }
+        .button { background-color: #007bff; color: white; padding: 12px 24px; text-decoration: none; border-radius: 4px; display: inline-block; margin: 20px 0; }
+        .footer { margin-top: 40px; padding-top: 20px; border-top: 1px solid #ddd; font-size: 12px; color: #666; }
+      </style>
+    </head>
+    <body>
+      <div class="container">
+        <h1>Verify Your Sender Email Address</h1>
+        <p>Hello ${sender.name},</p>
+        <p>You've added <strong>${sender.email}</strong> as a sender email address for ${sender.provider}.</p>
+        <p>To complete the verification process, please click the button below:</p>
+        <a href="${verificationUrl}" class="button">Verify Email Address</a>
+        <p>Or copy and paste this URL into your browser:</p>
+        <p>${verificationUrl}</p>
+        <p><strong>This link will expire in 24 hours.</strong></p>
+        <div class="footer">
+          <p>If you didn't request this verification, please ignore this email.</p>
+          <p>Sender ID: ${sender.id}</p>
+        </div>
+      </div>
+    </body>
+    </html>
+  `;
+}
+/**
+ * Build plain text verification email
+ */
+function buildVerificationEmailText(sender, verificationUrl) {
+    return `
+Verify Your Sender Email Address
+
+Hello ${sender.name},
+
+You've added ${sender.email} as a sender email address for ${sender.provider}.
+
+To complete the verification process, please visit:
+
+${verificationUrl}
+
+This link will expire in 24 hours.
+
+If you didn't request this verification, please ignore this email.
+
+Sender ID: ${sender.id}
+  `.trim();
+}

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Sender identity record
+ */
+export interface SenderIdentity {
+    id: string;
+    email: string;
+    name: string;
+    replyToEmail?: string;
+    replyToName?: string;
+    domain: string;
+    provider: EmailProvider;
+    status: SenderStatus;
+    isDefault: boolean;
+    isActive: boolean;
+    verifiedAt?: Date;
+    verificationToken?: string;
+    verificationSentAt?: Date;
+    verificationExpiresAt?: Date;
+    verificationAttempts: number;
+    providerSenderId?: string;
+    providerMetadata?: Record<string, unknown>;
+    lastValidated?: Date;
+    validationErrors?: string[];
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt?: Date;
+}
+/**
+ * Sender status enum
+ */
+export declare enum SenderStatus {
+    PENDING = "pending",// Created, awaiting verification
+    VERIFICATION_SENT = "verification_sent",// Verification email sent
+    VERIFIED = "verified",// Email verified, ready to use
+    FAILED = "failed",// Verification failed
+    EXPIRED = "expired",// Verification token expired
+    LOCKED = "locked",// Too many failed attempts
+    INACTIVE = "inactive"
+}
+/**
+ * Email provider enum
+ */
+export declare enum EmailProvider {
+    SENDGRID = "sendgrid",
+    MAILGUN = "mailgun",
+    SES = "ses",
+    SMTP = "smtp"
+}
+/**
+ * Sender creation input
+ */
+export interface CreateSenderInput {
+    email: string;
+    name: string;
+    replyToEmail?: string;
+    replyToName?: string;
+    provider: EmailProvider;
+    isDefault?: boolean;
+    skipVerification?: boolean;
+}
+/**
+ * Sender update input
+ */
+export interface UpdateSenderInput {
+    name?: string;
+    replyToEmail?: string;
+    replyToName?: string;
+    isDefault?: boolean;
+    isActive?: boolean;
+}
+/**
+ * Verification result
+ */
+export interface VerificationResult {
+    success: boolean;
+    senderId: string;
+    status: SenderStatus;
+    message: string;
+    verifiedAt?: Date;
+    errors?: string[];
+}
+/**
+ * Provider compliance check result
+ */
+export interface ComplianceCheckResult {
+    isCompliant: boolean;
+    checks: {
+        domainVerified: boolean;
+        spfValid: boolean;
+        dkimValid: boolean;
+        emailFormat: boolean;
+    };
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Sender list options
+ */
+export interface ListSendersOptions {
+    provider?: EmailProvider;
+    status?: SenderStatus;
+    isActive?: boolean;
+    domain?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Package result wrapper
+ */
+export interface SenderIdentityResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    errors?: string[];
+}
+/**
+ * Domain verification status (interface for missing @bernierllc/email-domain-verification)
+ * TODO: Replace with actual import when email-domain-verification package is available
+ */
+export interface DomainVerificationStatus {
+    isVerified: boolean;
+    domain: string;
+    verificationUrl?: string;
+    dnsRecords?: {
+        spf?: {
+            isValid: boolean;
+        };
+        dkim?: {
+            isValid: boolean;
+        };
+    };
+}
+/**
+ * Email domain verification interface (stub for missing dependency)
+ * TODO: Replace with actual @bernierllc/email-domain-verification when available
+ */
+export interface IEmailDomainVerification {
+    getDomainStatus(domain: string): Promise<DomainVerificationStatus>;
+}