@bernierllc/sender-identity-verification 3.0.2 → 3.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/config.ts DELETED
@@ -1,90 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { IEmailDomainVerification } from './types.js';
10
- import type { EmailSenderManager, SenderProviderPlugin } from '@bernierllc/email-sender-manager';
11
-
12
- /**
13
- * Configuration for sender identity verification service
14
- */
15
- export interface SenderIdentityConfig {
16
- // Email sender configuration (for sending verification emails)
17
- emailSenderConfig: {
18
- provider?: string;
19
- apiKey?: string;
20
- };
21
-
22
- // Domain verification configuration
23
- domainVerificationConfig: {
24
- instance?: IEmailDomainVerification;
25
- };
26
-
27
- // Core sender manager for persistence (optional for backward compat)
28
- senderManager?: EmailSenderManager;
29
-
30
- // Provider plugins for API-driven sender operations (optional for backward compat)
31
- providerPlugins?: SenderProviderPlugin[];
32
-
33
- // Retry configuration
34
- retryConfig?: {
35
- maxRetries?: number;
36
- initialDelayMs?: number;
37
- maxDelayMs?: number;
38
- };
39
-
40
- // Verification settings
41
- verificationBaseUrl: string;
42
- verificationFromEmail: string;
43
- verificationFromName: string;
44
-
45
- // Provider API keys (legacy — prefer providerPlugins)
46
- sendgridApiKey?: string;
47
- mailgunApiKey?: string;
48
- sesAccessKey?: string;
49
- sesSecretKey?: string;
50
- sesRegion?: string;
51
-
52
- // Database configuration
53
- databaseUrl?: string;
54
- }
55
-
56
- /**
57
- * Load configuration from environment variables
58
- */
59
- export function loadConfigFromEnv(overrides: Partial<SenderIdentityConfig> = {}): SenderIdentityConfig {
60
- const config: SenderIdentityConfig = {
61
- verificationBaseUrl: process.env.SENDER_VERIFICATION_BASE_URL || overrides.verificationBaseUrl || '',
62
- verificationFromEmail: process.env.SENDER_VERIFICATION_FROM_EMAIL || overrides.verificationFromEmail || 'noreply@example.com',
63
- verificationFromName: process.env.SENDER_VERIFICATION_FROM_NAME || overrides.verificationFromName || 'Email Verification',
64
-
65
- sendgridApiKey: process.env.SENDGRID_API_KEY || overrides.sendgridApiKey,
66
- mailgunApiKey: process.env.MAILGUN_API_KEY || overrides.mailgunApiKey,
67
- sesAccessKey: process.env.AWS_SES_ACCESS_KEY || overrides.sesAccessKey,
68
- sesSecretKey: process.env.AWS_SES_SECRET_KEY || overrides.sesSecretKey,
69
- sesRegion: process.env.AWS_SES_REGION || overrides.sesRegion || 'us-east-1',
70
-
71
- databaseUrl: process.env.DATABASE_URL || overrides.databaseUrl,
72
-
73
- emailSenderConfig: overrides.emailSenderConfig || {},
74
- domainVerificationConfig: overrides.domainVerificationConfig || {},
75
- senderManager: overrides.senderManager,
76
- providerPlugins: overrides.providerPlugins,
77
- retryConfig: overrides.retryConfig
78
- };
79
-
80
- // Log configuration (without sensitive data)
81
- console.log('⚙️ Sender Identity Verification Configuration:');
82
- console.log(` └── Verification Base URL: ${config.verificationBaseUrl || '(not set)'}`);
83
- console.log(` └── From Email: ${config.verificationFromEmail}`);
84
- console.log(` └── SendGrid: ${config.sendgridApiKey ? '***configured***' : '(not set)'}`);
85
- console.log(` └── Mailgun: ${config.mailgunApiKey ? '***configured***' : '(not set)'}`);
86
- console.log(` └── SES: ${config.sesAccessKey ? '***configured***' : '(not set)'}`);
87
- console.log(` └── Database: ${config.databaseUrl ? '***configured***' : '(not set)'}`);
88
-
89
- return config;
90
- }
package/src/errors.ts DELETED
@@ -1,90 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { SenderIdentityResult } from './types.js';
10
-
11
- /**
12
- * Typed error code union for sender-identity-verification errors.
13
- *
14
- * Replaces the previous `SenderErrorCode` enum (removed in 2.0.0).
15
- * Consumers should use the string literal directly, e.g. `'SENDER_NOT_FOUND'`.
16
- */
17
- export type SenderVerificationErrorCode =
18
- | 'SENDER_VERIFICATION_ERROR'
19
- | 'SENDER_NOT_FOUND'
20
- | 'SENDER_ALREADY_EXISTS'
21
- | 'SENDER_LOCKED'
22
- | 'VERIFICATION_EXPIRED'
23
- | 'VERIFICATION_FAILED'
24
- | 'DOMAIN_NOT_VERIFIED'
25
- | 'PROVIDER_ERROR'
26
- | 'INVALID_EMAIL'
27
- | 'RATE_LIMIT_EXCEEDED';
28
-
29
- /**
30
- * Options bag accepted by `SenderVerificationError`.
31
- *
32
- * - `cause`: chained underlying error (ES2022 Error.cause).
33
- * - `code`: a typed error code from {@link SenderVerificationErrorCode}.
34
- * - `context`: arbitrary structured context — senderId/details/etc.
35
- * The legacy `details` ctor argument is now stored under `context.details`.
36
- */
37
- export interface SenderVerificationErrorOptions {
38
- cause?: Error;
39
- code?: SenderVerificationErrorCode;
40
- context?: Record<string, unknown>;
41
- }
42
-
43
- /**
44
- * Custom error class for sender verification errors.
45
- *
46
- * Uses native ES2022 `Error.cause` for error chaining — read the underlying
47
- * error via `error.cause`. Structured fields (senderId, details, etc.) live
48
- * on `error.context` since 2.0.0.
49
- */
50
- export class SenderVerificationError extends Error {
51
- public readonly code: SenderVerificationErrorCode;
52
- public readonly context?: Record<string, unknown>;
53
-
54
- constructor(message: string, options?: SenderVerificationErrorOptions) {
55
- super(message, options?.cause ? { cause: options.cause } : undefined);
56
- this.name = 'SenderVerificationError';
57
- this.code = options?.code ?? 'SENDER_VERIFICATION_ERROR';
58
- if (options?.context !== undefined) {
59
- this.context = options.context;
60
- }
61
- Error.captureStackTrace?.(this, this.constructor);
62
- }
63
- }
64
-
65
- /**
66
- * Error handling wrapper — converts arbitrary errors to a
67
- * `SenderIdentityResult<never>` envelope. Reads `error.code` (now a string
68
- * literal under the new union) to populate `errors`.
69
- */
70
- export function handleSenderError(error: unknown): SenderIdentityResult<never> {
71
- if (error instanceof SenderVerificationError) {
72
- return {
73
- success: false,
74
- error: error.message,
75
- errors: [error.code]
76
- };
77
- }
78
-
79
- if (error instanceof Error) {
80
- return {
81
- success: false,
82
- error: error.message
83
- };
84
- }
85
-
86
- return {
87
- success: false,
88
- error: 'Unknown error occurred'
89
- };
90
- }
package/src/global.d.ts DELETED
@@ -1,24 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- // Node.js global types
10
- declare const process: {
11
- env: {
12
- [key: string]: string | undefined;
13
- };
14
- };
15
-
16
- // Fetch API types (minimal declaration)
17
- declare function fetch(url: string, init?: {
18
- method?: string;
19
- headers?: Record<string, string>;
20
- body?: string;
21
- }): Promise<{
22
- ok: boolean;
23
- json(): Promise<unknown>;
24
- }>;
package/src/index.ts DELETED
@@ -1,33 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- export { SenderIdentityVerification } from './SenderIdentityVerification.js';
10
- export { SenderIdentityConfig, loadConfigFromEnv } from './config.js';
11
- export {
12
- SenderVerificationError,
13
- handleSenderError
14
- } from './errors.js';
15
- export type {
16
- SenderVerificationErrorCode,
17
- SenderVerificationErrorOptions
18
- } from './errors.js';
19
- export {
20
- SenderIdentity,
21
- SenderStatus,
22
- EmailProvider,
23
- CreateSenderInput,
24
- UpdateSenderInput,
25
- VerificationResult,
26
- ComplianceCheckResult,
27
- ListSendersOptions,
28
- SenderIdentityResult,
29
- DomainVerificationStatus,
30
- IEmailDomainVerification
31
- } from './types.js';
32
- export { getManualInstructions, isManualVerificationProvider } from './manual-instructions.js';
33
- export type { ManualVerificationInstruction } from './manual-instructions.js';
@@ -1,61 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { EmailProvider } from './types.js';
10
-
11
- export interface ManualVerificationInstruction {
12
- provider: EmailProvider;
13
- title: string;
14
- steps: string[];
15
- dashboardUrl?: string;
16
- }
17
-
18
- const MANUAL_INSTRUCTIONS: Record<string, ManualVerificationInstruction> = {
19
- [EmailProvider.SMTP]: {
20
- provider: EmailProvider.SMTP,
21
- title: 'SMTP Sender Verification',
22
- steps: [
23
- 'Configure your SMTP server to allow sending from this address.',
24
- 'Ensure SPF records include your SMTP server IP.',
25
- 'Configure DKIM signing for the domain.',
26
- 'Mark the sender as verified once DNS records are propagated.',
27
- ],
28
- },
29
- [EmailProvider.SMTP2GO]: {
30
- provider: EmailProvider.SMTP2GO,
31
- title: 'SMTP2GO Sender Verification',
32
- steps: [
33
- 'Log in to your SMTP2GO dashboard.',
34
- 'Navigate to Settings → Sender Domains.',
35
- 'Add and verify the sender domain.',
36
- 'Mark the sender as verified once domain is confirmed.',
37
- ],
38
- dashboardUrl: 'https://app.smtp2go.com/settings/sender_domains/',
39
- },
40
- [EmailProvider.MANDRILL]: {
41
- provider: EmailProvider.MANDRILL,
42
- title: 'Mandrill Sender Verification',
43
- steps: [
44
- 'Log in to your Mandrill dashboard.',
45
- 'Navigate to Settings → Sending Domains.',
46
- 'Add and verify the sender domain.',
47
- 'Mark the sender as verified once domain is confirmed.',
48
- ],
49
- dashboardUrl: 'https://mandrillapp.com/settings/sending-domains',
50
- },
51
- };
52
-
53
- export function getManualInstructions(provider: EmailProvider): ManualVerificationInstruction | null {
54
- return MANUAL_INSTRUCTIONS[provider] || null;
55
- }
56
-
57
- export function isManualVerificationProvider(provider: EmailProvider): boolean {
58
- return provider === EmailProvider.SMTP
59
- || provider === EmailProvider.SMTP2GO
60
- || provider === EmailProvider.MANDRILL;
61
- }
@@ -1,35 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { SenderIdentity, SenderIdentityResult } from '../types.js';
10
-
11
- /**
12
- * Mailgun provider for sender verification
13
- * Note: Mailgun doesn't have sender-level verification, only domain verification
14
- */
15
- export class MailgunProvider {
16
- constructor(_apiKey: string) {
17
- // apiKey parameter reserved for future Mailgun API integration
18
- void _apiKey;
19
- }
20
-
21
- /**
22
- * Verify sender with Mailgun
23
- * Mailgun only verifies domains, not individual senders
24
- */
25
- async verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>> {
26
- // Mailgun doesn't require individual sender verification
27
- // Domain verification is handled by @bernierllc/email-domain-verification
28
- return {
29
- success: true,
30
- data: {
31
- note: 'Mailgun does not require individual sender verification'
32
- }
33
- };
34
- }
35
- }
@@ -1,51 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { SenderIdentity, SenderIdentityResult } from '../types.js';
10
-
11
- /**
12
- * AWS SES provider for sender verification
13
- */
14
- export class SESProvider {
15
- constructor(
16
- _accessKey: string,
17
- _secretKey: string,
18
- _region: string
19
- ) {
20
- // Parameters reserved for future AWS SDK integration
21
- void _accessKey;
22
- void _secretKey;
23
- void _region;
24
- }
25
-
26
- /**
27
- * Verify sender with AWS SES
28
- * TODO: Implement AWS SDK integration for SES VerifyEmailIdentity
29
- */
30
- async verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>> {
31
- try {
32
- // TODO: Call SES VerifyEmailIdentity API
33
- // For now, return success (stub implementation)
34
- // Real implementation would use AWS SDK:
35
- // const ses = new SES({ region: this.region, credentials: {...} });
36
- // await ses.verifyEmailIdentity({ EmailAddress: sender.email });
37
-
38
- return {
39
- success: true,
40
- data: {
41
- note: 'SES verification stubbed - AWS SDK integration pending'
42
- }
43
- };
44
- } catch (error) {
45
- return {
46
- success: false,
47
- error: error instanceof Error ? error.message : 'SES verification failed'
48
- };
49
- }
50
- }
51
- }
@@ -1,29 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { SenderIdentity, SenderIdentityResult } from '../types.js';
10
-
11
- /**
12
- * SMTP provider for sender verification
13
- * Note: SMTP doesn't require provider-level verification
14
- */
15
- export class SMTPProvider {
16
- /**
17
- * Verify sender with SMTP
18
- * SMTP doesn't require provider verification - just email validation
19
- */
20
- async verifySender(_sender: SenderIdentity): Promise<SenderIdentityResult<Record<string, unknown>>> {
21
- // SMTP doesn't require provider-level verification
22
- return {
23
- success: true,
24
- data: {
25
- note: 'SMTP does not require provider-level verification'
26
- }
27
- };
28
- }
29
- }
@@ -1,108 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { SenderIdentity, SenderIdentityResult } from '../types.js';
10
-
11
- /**
12
- * SendGrid provider for sender verification
13
- */
14
- export class SendGridProvider {
15
- constructor(private apiKey: string) {}
16
-
17
- /**
18
- * Verify sender with SendGrid
19
- */
20
- async verifySender(sender: SenderIdentity): Promise<SenderIdentityResult<{
21
- providerId: string;
22
- metadata: Record<string, unknown>;
23
- }>> {
24
- try {
25
- if (!this.apiKey) {
26
- return {
27
- success: false,
28
- error: 'SendGrid API key not configured'
29
- };
30
- }
31
-
32
- // Create verified sender in SendGrid
33
- const response = await this.sendGridRequest('POST', '/verified_senders', {
34
- nickname: sender.name,
35
- from_email: sender.email,
36
- from_name: sender.name,
37
- reply_to: sender.replyToEmail,
38
- reply_to_name: sender.replyToName,
39
- address: '123 Main St',
40
- city: 'Anytown',
41
- state: 'CA', // Must be 2-character state code per SendGrid API requirements
42
- zip: '12345',
43
- country: 'US'
44
- });
45
-
46
- if (!response.success) {
47
- return {
48
- success: false,
49
- error: 'SendGrid verification failed',
50
- errors: [response.error || 'Unknown SendGrid error']
51
- };
52
- }
53
-
54
- return {
55
- success: true,
56
- data: {
57
- providerId: response.data?.id as string || '',
58
- metadata: response.data || {}
59
- }
60
- };
61
- } catch (error) {
62
- return {
63
- success: false,
64
- error: error instanceof Error ? error.message : 'SendGrid verification failed'
65
- };
66
- }
67
- }
68
-
69
- /**
70
- * Make SendGrid API request
71
- */
72
- private async sendGridRequest(
73
- method: string,
74
- path: string,
75
- body?: Record<string, unknown>
76
- ): Promise<SenderIdentityResult<Record<string, unknown>>> {
77
- try {
78
- const response = await fetch(`https://api.sendgrid.com/v3${path}`, {
79
- method,
80
- headers: {
81
- 'Authorization': `Bearer ${this.apiKey}`,
82
- 'Content-Type': 'application/json'
83
- },
84
- body: body ? JSON.stringify(body) : undefined
85
- });
86
-
87
- const data = await response.json() as { errors?: Array<{ message: string }>; id?: string };
88
-
89
- if (!response.ok) {
90
- return {
91
- success: false,
92
- error: data.errors?.[0]?.message || 'SendGrid API error',
93
- errors: data.errors?.map((e) => e.message)
94
- };
95
- }
96
-
97
- return {
98
- success: true,
99
- data: data as Record<string, unknown>
100
- };
101
- } catch (error) {
102
- return {
103
- success: false,
104
- error: error instanceof Error ? error.message : 'SendGrid request failed'
105
- };
106
- }
107
- }
108
- }
@@ -1,67 +0,0 @@
1
- /*
2
- Copyright (c) 2025 Bernier LLC
3
-
4
- This file is licensed to the client under a limited-use license.
5
- The client may use and modify this code *only within the scope of the project it was delivered for*.
6
- Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
- */
8
-
9
- import { SenderIdentity } from '../types.js';
10
-
11
- /**
12
- * Build HTML verification email
13
- */
14
- export function buildVerificationEmailHtml(sender: SenderIdentity, verificationUrl: string): string {
15
- return `
16
- <!DOCTYPE html>
17
- <html>
18
- <head>
19
- <style>
20
- body { font-family: Arial, sans-serif; line-height: 1.6; color: #333; }
21
- .container { max-width: 600px; margin: 0 auto; padding: 20px; }
22
- .button { background-color: #007bff; color: white; padding: 12px 24px; text-decoration: none; border-radius: 4px; display: inline-block; margin: 20px 0; }
23
- .footer { margin-top: 40px; padding-top: 20px; border-top: 1px solid #ddd; font-size: 12px; color: #666; }
24
- </style>
25
- </head>
26
- <body>
27
- <div class="container">
28
- <h1>Verify Your Sender Email Address</h1>
29
- <p>Hello ${sender.name},</p>
30
- <p>You've added <strong>${sender.email}</strong> as a sender email address for ${sender.provider}.</p>
31
- <p>To complete the verification process, please click the button below:</p>
32
- <a href="${verificationUrl}" class="button">Verify Email Address</a>
33
- <p>Or copy and paste this URL into your browser:</p>
34
- <p>${verificationUrl}</p>
35
- <p><strong>This link will expire in 24 hours.</strong></p>
36
- <div class="footer">
37
- <p>If you didn't request this verification, please ignore this email.</p>
38
- <p>Sender ID: ${sender.id}</p>
39
- </div>
40
- </div>
41
- </body>
42
- </html>
43
- `;
44
- }
45
-
46
- /**
47
- * Build plain text verification email
48
- */
49
- export function buildVerificationEmailText(sender: SenderIdentity, verificationUrl: string): string {
50
- return `
51
- Verify Your Sender Email Address
52
-
53
- Hello ${sender.name},
54
-
55
- You've added ${sender.email} as a sender email address for ${sender.provider}.
56
-
57
- To complete the verification process, please visit:
58
-
59
- ${verificationUrl}
60
-
61
- This link will expire in 24 hours.
62
-
63
- If you didn't request this verification, please ignore this email.
64
-
65
- Sender ID: ${sender.id}
66
- `.trim();
67
- }