@bernierllc/email-domain-verification 1.0.0

package/src/dns2.d.ts

@@ -0,0 +1,29 @@
+/*
+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.
+*/
+
+declare module 'dns2' {
+  export interface ResolverOptions {
+    nameServers?: string[];
+    timeout?: number;
+  }
+
+  export interface DNSAnswer {
+    type: string;
+    data: string;
+    ns?: string;
+  }
+
+  export interface DNSResponse {
+    answers: DNSAnswer[];
+  }
+
+  export class Resolver {
+    constructor(options?: ResolverOptions);
+    resolve(hostname: string, recordType: string): Promise<DNSResponse>;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,79 @@
+/*
+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.
+*/
+
+/**
+ * Domain verification error types
+ */
+export class DomainVerificationError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable = false,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = 'DomainVerificationError';
+  }
+}
+
+export class DNSPropagationError extends DomainVerificationError {
+  constructor(message: string, details?: unknown) {
+    super(message, 'DNS_PROPAGATION_ERROR', true, details);
+    this.name = 'DNSPropagationError';
+  }
+}
+
+export class ProviderAPIError extends DomainVerificationError {
+  constructor(message: string, details?: unknown) {
+    super(message, 'PROVIDER_API_ERROR', true, details);
+    this.name = 'ProviderAPIError';
+  }
+}
+
+export class InvalidDomainError extends DomainVerificationError {
+  constructor(message: string, details?: unknown) {
+    super(message, 'INVALID_DOMAIN', false, details);
+    this.name = 'InvalidDomainError';
+  }
+}
+
+/**
+ * Structured result pattern for all service operations
+ */
+export interface ServiceResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: unknown;
+  };
+}
+
+/**
+ * Helper to create success result
+ */
+export function successResult<T>(data: T): ServiceResult<T> {
+  return { success: true, data };
+}
+
+/**
+ * Helper to create error result
+ */
+export function errorResult(error: DomainVerificationError): ServiceResult {
+  return {
+    success: false,
+    error: {
+      code: error.code,
+      message: error.message,
+      retryable: error.retryable,
+      details: error.details
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/*
+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.
+*/
+
+export { EmailDomainVerificationService } from './EmailDomainVerificationService';
+export * from './types';
+export * from './errors';

package/src/types.ts

@@ -0,0 +1,281 @@
+/*
+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.
+*/
+
+/**
+ * Email provider types supported for domain verification
+ */
+export type EmailProvider = 'sendgrid' | 'mailgun' | 'ses' | 'custom';
+
+/**
+ * DNS record types for email authentication
+ */
+export type DNSRecordType = 'SPF' | 'DKIM' | 'DMARC' | 'MX' | 'TXT' | 'CNAME';
+
+/**
+ * Domain verification status
+ */
+export type VerificationStatus =
+  | 'pending'        // DNS records generated, awaiting propagation
+  | 'propagating'    // DNS records detected, propagating across nameservers
+  | 'verified'       // Domain fully verified by provider
+  | 'failed'         // Verification failed
+  | 'expired'        // Verification expired, needs re-verification
+  | 'suspended';     // Domain suspended by provider
+
+/**
+ * DNS record configuration for email authentication
+ */
+export interface DNSRecord {
+  /** Record type (SPF, DKIM, DMARC, etc.) */
+  type: DNSRecordType;
+
+  /** Hostname for the record */
+  host: string;
+
+  /** Record value/content */
+  value: string;
+
+  /** TTL in seconds */
+  ttl: number;
+
+  /** Priority (for MX records) */
+  priority?: number;
+
+  /** Provider that requires this record */
+  provider: EmailProvider;
+
+  /** Whether this record is required or optional */
+  required: boolean;
+
+  /** Human-readable instructions */
+  instructions: string;
+}
+
+/**
+ * DKIM configuration and keypair
+ */
+export interface DKIMConfig {
+  /** DKIM selector (e.g., 'default', 'k1', 's1') */
+  selector: string;
+
+  /** DKIM private key (PEM format) */
+  privateKey: string;
+
+  /** DKIM public key (PEM format) */
+  publicKey: string;
+
+  /** Key size in bits (1024, 2048) */
+  keySize: 1024 | 2048;
+
+  /** DNS record for DKIM public key */
+  dnsRecord: DNSRecord;
+
+  /** Provider-specific DKIM configuration */
+  providerConfig?: Record<string, unknown>;
+}
+
+/**
+ * Domain verification configuration
+ */
+export interface DomainConfig {
+  /** Domain name (e.g., 'example.com') */
+  domain: string;
+
+  /** Email provider to use */
+  provider: EmailProvider;
+
+  /** Provider API credentials */
+  providerCredentials: {
+    apiKey?: string;
+    apiSecret?: string;
+    region?: string; // For AWS SES
+    smtpPassword?: string; // For Mailgun
+    [key: string]: unknown;
+  };
+
+  /** DKIM configuration */
+  dkim: {
+    enabled: boolean;
+    selector?: string;
+    keySize?: 1024 | 2048;
+  };
+
+  /** SPF configuration */
+  spf: {
+    enabled: boolean;
+    includes?: string[]; // Additional includes
+    ipv4Addresses?: string[];
+    ipv6Addresses?: string[];
+    strict?: boolean; // Use -all vs ~all
+  };
+
+  /** DMARC configuration */
+  dmarc: {
+    enabled: boolean;
+    policy?: 'none' | 'quarantine' | 'reject';
+    percentage?: number;
+    reportEmail?: string;
+    aggregateEmail?: string;
+    subdomain?: 'none' | 'quarantine' | 'reject';
+  };
+
+  /** MX records configuration */
+  mx?: {
+    enabled: boolean;
+    records?: Array<{ priority: number; host: string }>;
+  };
+
+  /** Verification callback URL */
+  callbackUrl?: string;
+
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Domain verification result
+ */
+export interface DomainVerificationResult {
+  /** Verification success status */
+  success: boolean;
+
+  /** Domain name */
+  domain: string;
+
+  /** Current verification status */
+  status: VerificationStatus;
+
+  /** DNS records to configure */
+  dnsRecords: DNSRecord[];
+
+  /** DKIM configuration (if enabled) */
+  dkimConfig?: DKIMConfig;
+
+  /** Verification errors (if any) */
+  errors?: string[];
+
+  /** Provider-specific verification data */
+  providerData?: Record<string, unknown>;
+
+  /** Estimated propagation time (seconds) */
+  estimatedPropagationTime?: number;
+
+  /** Next steps for user */
+  nextSteps?: string[];
+}
+
+/**
+ * DNS propagation check result
+ */
+export interface DNSPropagationResult {
+  /** Domain name */
+  domain: string;
+
+  /** DNS record being checked */
+  record: DNSRecord;
+
+  /** Whether record is propagated */
+  propagated: boolean;
+
+  /** Nameservers checked */
+  nameservers: string[];
+
+  /** Propagation percentage (0-100) */
+  propagationPercentage: number;
+
+  /** Actual DNS value found */
+  actualValue?: string;
+
+  /** Expected DNS value */
+  expectedValue: string;
+
+  /** Values match */
+  valuesMatch: boolean;
+
+  /** Errors encountered */
+  errors?: string[];
+}
+
+/**
+ * Domain health status
+ */
+export interface DomainHealthStatus {
+  /** Domain name */
+  domain: string;
+
+  /** Overall health status */
+  healthy: boolean;
+
+  /** Verification status */
+  verificationStatus: VerificationStatus;
+
+  /** Last verification check timestamp */
+  lastChecked: Date;
+
+  /** Individual record health */
+  records: Array<{
+    type: DNSRecordType;
+    healthy: boolean;
+    lastChecked: Date;
+    error?: string;
+  }>;
+
+  /** Provider-specific health data */
+  providerHealth?: {
+    connected: boolean;
+    lastApiCall: Date;
+    error?: string;
+  };
+
+  /** Warnings */
+  warnings?: string[];
+
+  /** Recommendations */
+  recommendations?: string[];
+}
+
+/**
+ * Verification history entry
+ */
+export interface VerificationHistoryEntry {
+  /** Entry ID */
+  id: string;
+
+  /** Domain name */
+  domain: string;
+
+  /** Timestamp */
+  timestamp: Date;
+
+  /** Event type */
+  eventType: 'initiated' | 'dns-updated' | 'propagated' | 'verified' | 'failed' | 'expired';
+
+  /** Event details */
+  details: string;
+
+  /** Previous status */
+  previousStatus?: VerificationStatus;
+
+  /** New status */
+  newStatus?: VerificationStatus;
+
+  /** User who triggered event */
+  triggeredBy?: string;
+
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result type for domain verification operations
+ */
+export interface DomainVerificationServiceResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "jsx": "react"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}