@stacksjs/ts-cloud-core 0.1.6 → 0.1.7

package/dist/email/handlers/outbound.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Outbound Email Lambda Handler
+ *
+ * Processes outgoing emails:
+ * - Accepts JSON email payloads from S3
+ * - Generates proper MIME messages
+ * - Supports HTML and plain text
+ * - Handles attachments (base64 encoded)
+ * - Tracks via configuration set
+ * - Stores sent emails in S3
+ */
+export declare const handler: `
+const { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand } = require('@aws-sdk/client-s3');
+const { SESClient, SendRawEmailCommand } = require('@aws-sdk/client-ses');
+
+const s3 = new S3Client({});
+const ses = new SESClient({});
+
+exports.handler = async (event) => {
+  console.log('Outbound email event:', JSON.stringify(event, null, 2));
+
+  const bucket = process.env.EMAIL_BUCKET;
+  const configSet = process.env.CONFIG_SET || 'default';
+
+  for (const record of event.Records) {
+    try {
+      // Get the email payload from S3
+      const s3Event = record.s3 || {};
+      const key = decodeURIComponent(s3Event.object?.key?.replace(/\\+/g, ' ') || '');
+
+      if (!key || !key.startsWith('outbox/')) {
+        continue;
+      }
+
+      const getResult = await s3.send(new GetObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      }));
+
+      const emailData = JSON.parse(await getResult.Body.transformToString());
+
+      // Build MIME message
+      const boundary = \`----=_Part_\${Date.now()}_\${Math.random().toString(36).substr(2)}\`;
+      const mixedBoundary = \`----=_Mixed_\${Date.now()}_\${Math.random().toString(36).substr(2)}\`;
+
+      let rawMessage = '';
+
+      // Headers
+      rawMessage += \`From: \${emailData.from}\\r\\n\`;
+      rawMessage += \`To: \${Array.isArray(emailData.to) ? emailData.to.join(', ') : emailData.to}\\r\\n\`;
+
+      if (emailData.cc) {
+        rawMessage += \`Cc: \${Array.isArray(emailData.cc) ? emailData.cc.join(', ') : emailData.cc}\\r\\n\`;
+      }
+
+      if (emailData.replyTo) {
+        rawMessage += \`Reply-To: \${emailData.replyTo}\\r\\n\`;
+      }
+
+      rawMessage += \`Subject: =?UTF-8?B?\${Buffer.from(emailData.subject || '').toString('base64')}?=\\r\\n\`;
+      rawMessage += \`Date: \${new Date().toUTCString()}\\r\\n\`;
+      rawMessage += \`Message-ID: <\${Date.now()}.\${Math.random().toString(36)}@\${emailData.from.split('@')[1] || 'local'}>\\r\\n\`;
+      rawMessage += 'MIME-Version: 1.0\\r\\n';
+
+      const hasAttachments = emailData.attachments && emailData.attachments.length > 0;
+
+      if (hasAttachments) {
+        rawMessage += \`Content-Type: multipart/mixed; boundary="\${mixedBoundary}"\\r\\n\\r\\n\`;
+        rawMessage += \`--\${mixedBoundary}\\r\\n\`;
+      }
+
+      // Body (multipart alternative for HTML + text)
+      if (emailData.html && emailData.text) {
+        rawMessage += \`Content-Type: multipart/alternative; boundary="\${boundary}"\\r\\n\\r\\n\`;
+
+        // Plain text part
+        rawMessage += \`--\${boundary}\\r\\n\`;
+        rawMessage += 'Content-Type: text/plain; charset=UTF-8\\r\\n';
+        rawMessage += 'Content-Transfer-Encoding: quoted-printable\\r\\n\\r\\n';
+        rawMessage += emailData.text + '\\r\\n\\r\\n';
+
+        // HTML part
+        rawMessage += \`--\${boundary}\\r\\n\`;
+        rawMessage += 'Content-Type: text/html; charset=UTF-8\\r\\n';
+        rawMessage += 'Content-Transfer-Encoding: quoted-printable\\r\\n\\r\\n';
+        rawMessage += emailData.html + '\\r\\n\\r\\n';
+
+        rawMessage += \`--\${boundary}--\\r\\n\`;
+      } else if (emailData.html) {
+        if (!hasAttachments) {
+          rawMessage += 'Content-Type: text/html; charset=UTF-8\\r\\n';
+          rawMessage += 'Content-Transfer-Encoding: quoted-printable\\r\\n\\r\\n';
+        } else {
+          rawMessage += 'Content-Type: text/html; charset=UTF-8\\r\\n\\r\\n';
+        }
+        rawMessage += emailData.html + '\\r\\n';
+      } else {
+        if (!hasAttachments) {
+          rawMessage += 'Content-Type: text/plain; charset=UTF-8\\r\\n';
+          rawMessage += 'Content-Transfer-Encoding: quoted-printable\\r\\n\\r\\n';
+        } else {
+          rawMessage += 'Content-Type: text/plain; charset=UTF-8\\r\\n\\r\\n';
+        }
+        rawMessage += (emailData.text || emailData.body || '') + '\\r\\n';
+      }
+
+      // Attachments
+      if (hasAttachments) {
+        for (const attachment of emailData.attachments) {
+          rawMessage += \`--\${mixedBoundary}\\r\\n\`;
+          rawMessage += \`Content-Type: \${attachment.contentType || 'application/octet-stream'}; name="\${attachment.filename}"\\r\\n\`;
+          rawMessage += 'Content-Transfer-Encoding: base64\\r\\n';
+          rawMessage += \`Content-Disposition: attachment; filename="\${attachment.filename}"\\r\\n\\r\\n\`;
+          rawMessage += attachment.content + '\\r\\n';
+        }
+        rawMessage += \`--\${mixedBoundary}--\\r\\n\`;
+      }
+
+      // Send via SES
+      const sendResult = await ses.send(new SendRawEmailCommand({
+        RawMessage: { Data: Buffer.from(rawMessage) },
+        ConfigurationSetName: configSet,
+      }));
+
+      console.log(\`Email sent: \${sendResult.MessageId}\`);
+
+      // Store in sent folder
+      const timestamp = new Date();
+      const year = timestamp.getFullYear();
+      const month = String(timestamp.getMonth() + 1).padStart(2, '0');
+      const day = String(timestamp.getDate()).padStart(2, '0');
+
+      const fromEmail = emailData.from.match(/<([^>]+)>/) ? emailData.from.match(/<([^>]+)>/)[1] : emailData.from;
+      const [localPart, domain] = fromEmail.split('@');
+
+      const sentPath = \`mailboxes/\${domain}/\${localPart}/sent/\${year}/\${month}/\${day}/\${sendResult.MessageId}\`;
+
+      // Save sent email metadata
+      await s3.send(new PutObjectCommand({
+        Bucket: bucket,
+        Key: \`\${sentPath}/metadata.json\`,
+        Body: JSON.stringify({
+          messageId: sendResult.MessageId,
+          from: emailData.from,
+          to: emailData.to,
+          cc: emailData.cc,
+          subject: emailData.subject,
+          sentAt: timestamp.toISOString(),
+          hasAttachments,
+        }, null, 2),
+        ContentType: 'application/json',
+      }));
+
+      // Save raw message
+      await s3.send(new PutObjectCommand({
+        Bucket: bucket,
+        Key: \`\${sentPath}/raw.eml\`,
+        Body: rawMessage,
+        ContentType: 'message/rfc822',
+      }));
+
+      // Delete from outbox
+      await s3.send(new DeleteObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      }));
+
+    } catch (error) {
+      console.error('Error sending email:', error);
+    }
+  }
+
+  return { statusCode: 200, body: 'OK' };
+};
+`;
+export default handler;

package/dist/email/index.d.ts

@@ -0,0 +1,6 @@
+export * from './bounce-handling';
+export * from './analytics';
+export * from './reputation';
+export * from './templates';
+export * as EmailAdvanced from './advanced';
+export * as EmailHandlers from './handlers/inbound';

package/dist/email/reputation.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Global sender reputation manager instance
+ */
+export declare const senderReputationManager: SenderReputationManager;
+/**
+ * SES Sender Reputation Monitoring
+ * Reputation tracking, sending limits, and deliverability monitoring
+ */
+export declare interface ReputationDashboard {
+  id: string
+  timestamp: Date
+  overallScore: number
+  bounceRate: number
+  complaintRate: number
+  spamReports: number
+  blacklistStatus: BlacklistStatus[]
+  dkimStatus: 'VERIFIED' | 'PENDING' | 'FAILED'
+  spfStatus: 'PASS' | 'FAIL' | 'SOFTFAIL'
+  dmarcStatus: 'PASS' | 'FAIL' | 'NONE'
+  sendingLimits: SendingLimits
+  recommendations: string[]
+}
+export declare interface BlacklistStatus {
+  listName: string
+  listed: boolean
+  listedAt?: Date
+  delistUrl?: string
+}
+export declare interface SendingLimits {
+  maxSendRate: number
+  max24HourSend: number
+  sentLast24Hours: number
+  remainingQuota: number
+  quotaResetTime: Date
+}
+export declare interface WarmupPlan {
+  id: string
+  name: string
+  startDate: Date
+  currentDay: number
+  totalDays: number
+  dailyLimits: number[]
+  currentLimit: number
+  status: 'active' | 'paused' | 'completed'
+}
+export declare interface DomainReputation {
+  id: string
+  domain: string
+  reputationScore: number
+  totalSent: number
+  deliveryRate: number
+  openRate: number
+  clickRate: number
+  bounceRate: number
+  complaintRate: number
+  engagementScore: number
+}
+/**
+ * Sender reputation manager
+ */
+export declare class SenderReputationManager {
+  private dashboards: Map<string, ReputationDashboard>;
+  private warmupPlans: Map<string, WarmupPlan>;
+  private domainReputations: Map<string, DomainReputation>;
+  private dashboardCounter: any;
+  private warmupCounter: any;
+  private domainCounter: any;
+  getReputationDashboard(): ReputationDashboard;
+  private checkBlacklists(): BlacklistStatus[];
+  createWarmupPlan(options: {
+    name: string
+    initialDailyLimit: number
+    targetDailyLimit: number
+    durationDays: number
+  }): WarmupPlan;
+  createAggressiveWarmupPlan(options: {
+    name: string
+  }): WarmupPlan;
+  createConservativeWarmupPlan(options: {
+    name: string
+  }): WarmupPlan;
+  advanceWarmupPlan(warmupId: string): WarmupPlan;
+  trackDomainReputation(options: {
+    domain: string
+    totalSent: number
+    delivered: number
+    opened: number
+    clicked: number
+    bounced: number
+    complained: number
+  }): DomainReputation;
+  getDomainReputation(domain: string): DomainReputation | undefined;
+  listDomainReputations(): DomainReputation[];
+  getWarmupPlan(id: string): WarmupPlan | undefined;
+  listWarmupPlans(): WarmupPlan[];
+  clear(): void;
+}

package/dist/email/templates.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Global email template manager instance
+ */
+export declare const emailTemplateManager: EmailTemplateManager;
+/**
+ * SES Email Template Management
+ * Template versioning, personalization, and testing
+ */
+export declare interface EmailTemplate {
+  id: string
+  name: string
+  subject: string
+  htmlPart: string
+  textPart: string
+  variables: string[]
+  createdAt: Date
+  updatedAt: Date
+  version: number
+}
+export declare interface TemplateVersion {
+  id: string
+  templateId: string
+  version: number
+  subject: string
+  htmlPart: string
+  textPart: string
+  createdAt: Date
+  createdBy: string
+  changelog?: string
+}
+export declare interface TemplateTest {
+  id: string
+  templateId: string
+  testData: Record<string, any>
+  renderedSubject: string
+  renderedHtml: string
+  renderedText: string
+  timestamp: Date
+}
+/**
+ * Email template manager
+ */
+export declare class EmailTemplateManager {
+  private templates: Map<string, EmailTemplate>;
+  private versions: Map<string, TemplateVersion[]>;
+  private tests: Map<string, TemplateTest>;
+  private templateCounter: any;
+  private testCounter: any;
+  createTemplate(template: {
+    name: string
+    subject: string
+    htmlPart: string
+    textPart: string
+  }): EmailTemplate;
+  createWelcomeTemplate(options: {
+    name: string
+    companyName: string
+  }): EmailTemplate;
+  createPasswordResetTemplate(options: {
+    name: string
+    companyName: string
+  }): EmailTemplate;
+  updateTemplate(templateId: string, updates: {
+      subject?: string
+      htmlPart?: string
+      textPart?: string
+    }, changelog?: string): EmailTemplate;
+  private addVersion(version: Omit<TemplateVersion, 'id' | 'createdAt'>): TemplateVersion;
+  private extractVariables(text: string): string[];
+  renderTemplate(templateId: string, data: Record<string, any>): {
+    subject: string
+    html: string
+    text: string
+  };
+  testTemplate(templateId: string, testData: Record<string, any>): TemplateTest;
+  getTemplate(id: string): EmailTemplate | undefined;
+  listTemplates(): EmailTemplate[];
+  getTemplateVersions(templateId: string): TemplateVersion[];
+  revertToVersion(templateId: string, versionNumber: number): EmailTemplate;
+  generateTemplateCF(template: EmailTemplate): any;
+  clear(): void;
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Get error details by code
+ */
+export declare function getErrorDetails(code: keyof typeof ErrorCodes): { message: string; solution: string };
+/**
+ * Create error from code
+ */
+export declare function createError(code: keyof typeof ErrorCodes, additionalDetails?: Record<string, any>): CloudError;
+/**
+ * Validate configuration
+ */
+export declare function validateConfiguration(config: any): void;
+/**
+ * Detect common misconfigurations
+ */
+export declare function detectMisconfigurations(config: any): string[];
+/**
+ * Common error scenarios with solutions
+ */
+export declare const ErrorCodes: {
+  // Credential errors
+  NO_CREDENTIALS: {
+  message: 'AWS credentials not found';
+  solution: `Configure AWS credentials using one of these methods:
+  1. Set environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
+  2. Create ~/.aws/credentials file with your credentials
+  3. Use an IAM role (for EC2 instances)
+  4. Run 'aws configure' if you have AWS CLI installed`
+};
+  INVALID_CREDENTIALS: {
+  message: 'AWS credentials are invalid';
+  solution: 'Verify your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are correct. Run: aws sts get-caller-identity'
+};
+  EXPIRED_CREDENTIALS: {
+  message: 'AWS credentials have expired';
+  solution: 'Refresh your AWS credentials. If using temporary credentials, generate new ones.'
+};
+  // Configuration errors
+  MISSING_CONFIG: {
+  message: 'Configuration file not found';
+  solution: 'Create a cloud.config.ts file in your project root. Use: cloud init'
+};
+  INVALID_CONFIG: {
+  message: 'Configuration is invalid';
+  solution: 'Check your cloud.config.ts file for syntax errors. Use: cloud config:validate'
+};
+  MISSING_REQUIRED_FIELD: {
+  message: 'Required configuration field is missing';
+  solution: 'Add the missing field to your cloud.config.ts file'
+};
+  INVALID_REGION: {
+  message: 'AWS region is invalid';
+  solution: 'Use a valid AWS region like us-east-1, us-west-2, eu-west-1, etc.'
+};
+  // Deployment errors
+  STACK_ALREADY_EXISTS: {
+  message: 'CloudFormation stack already exists';
+  solution: 'Use: cloud deploy --update to update the existing stack, or cloud destroy to delete it first'
+};
+  STACK_IN_PROGRESS: {
+  message: 'Stack operation already in progress';
+  solution: 'Wait for the current operation to complete, or cancel it in the AWS Console'
+};
+  INSUFFICIENT_PERMISSIONS: {
+  message: 'Insufficient IAM permissions';
+  solution: 'Ensure your IAM user/role has the necessary permissions for CloudFormation and the resources you\'re deploying'
+};
+  RESOURCE_LIMIT_EXCEEDED: {
+  message: 'AWS service limit exceeded';
+  solution: 'Request a service limit increase in the AWS Console, or clean up unused resources'
+};
+  ROLLBACK_COMPLETE: {
+  message: 'Stack creation failed and rolled back';
+  solution: 'Check the CloudFormation events to see which resource failed. Fix the issue and try again.'
+};
+  // Validation errors
+  CIRCULAR_DEPENDENCY: {
+  message: 'Circular dependency detected in resources';
+  solution: 'Review your resource dependencies and remove the circular reference'
+};
+  INVALID_RESOURCE_NAME: {
+  message: 'Resource name contains invalid characters';
+  solution: 'Use only alphanumeric characters and hyphens in resource names'
+};
+  DUPLICATE_RESOURCE: {
+  message: 'Duplicate resource name detected';
+  solution: 'Ensure all resource names are unique in your configuration'
+};
+  // Network errors
+  VPC_CIDR_CONFLICT: {
+  message: 'VPC CIDR block conflicts with existing VPC';
+  solution: 'Use a different CIDR block that doesn\'t overlap with existing VPCs'
+};
+  SUBNET_CIDR_INVALID: {
+  message: 'Subnet CIDR block is invalid or outside VPC range';
+  solution: 'Ensure subnet CIDR is within the VPC CIDR range and properly sized'
+};
+  // Database errors
+  DB_INSTANCE_LIMIT: {
+  message: 'RDS instance limit reached';
+  solution: 'Delete unused RDS instances or request a limit increase'
+};
+  INVALID_DB_NAME: {
+  message: 'Database name contains invalid characters';
+  solution: 'Use only alphanumeric characters and underscores, starting with a letter'
+};
+  // S3 errors
+  BUCKET_ALREADY_EXISTS: {
+  message: 'S3 bucket name already exists globally';
+  solution: 'S3 bucket names must be globally unique. Try a different name with your organization prefix'
+};
+  INVALID_BUCKET_NAME: {
+  message: 'S3 bucket name is invalid';
+  solution: 'Use lowercase letters, numbers, and hyphens. Must start/end with letter/number. 3-63 characters.'
+};
+  // CloudFormation errors
+  TEMPLATE_TOO_LARGE: {
+  message: 'CloudFormation template exceeds size limit';
+  solution: 'Split your infrastructure into multiple stacks or use nested stacks'
+};
+  INVALID_TEMPLATE: {
+  message: 'CloudFormation template is invalid';
+  solution: 'Validate your template with: cloud config:validate'
+};
+  PARAMETER_NOT_FOUND: {
+  message: 'CloudFormation parameter not found';
+  solution: 'Check that all referenced parameters are defined in your template'
+}
+};
+/**
+ * Error Handling & Debugging
+ * Clear error messages with solutions and debugging support
+ */
+export declare class CloudError extends Error {
+  public code: string;
+  public solution?: string | undefined;
+  public details?: Record<string, any> | undefined;
+  constructor(message: string, code: string, solution?: string | undefined, details?: Record<string, any> | undefined);
+  toString(): string;
+}
+/**
+ * Configuration errors
+ */
+export declare class ConfigurationError extends CloudError {
+  constructor(message: string, solution?: string, details?: Record<string, any>);
+}
+/**
+ * AWS credential errors
+ */
+export declare class CredentialError extends CloudError {
+  constructor(message: string, solution?: string, details?: Record<string, any>);
+}
+/**
+ * Deployment errors
+ */
+export declare class DeploymentError extends CloudError {
+  constructor(message: string, solution?: string, details?: Record<string, any>);
+}
+/**
+ * Validation errors
+ */
+export declare class ValidationError extends CloudError {
+  constructor(message: string, solution?: string, details?: Record<string, any>);
+}
+/**
+ * AWS API errors
+ */
+export declare class AWSAPIError extends CloudError {
+  public statusCode?: number;
+  constructor(message: string, statusCode?: number, solution?: string, details?: Record<string, any>);
+}
+/**
+ * Debug logger
+ */
+export declare class DebugLogger {
+  static private verboseMode: any;
+  static private debugMode: any;
+  static setVerbose(enabled: boolean): void;
+  static setDebug(enabled: boolean): void;
+  static verbose(message: string, args: any[]): void;
+  static debug(message: string, args: any[]): void;
+  static info(message: string, args: any[]): void;
+  static warn(message: string, args: any[]): void;
+  static error(message: string, error?: Error): void;
+  static success(message: string): void;
+}

package/dist/health-checks/index.d.ts

@@ -0,0 +1,35 @@
+export declare const healthCheckManager: HealthCheckManager;
+/**
+ * Health Checks & Monitoring - Endpoint monitoring, synthetic monitoring, uptime tracking
+ */
+export declare interface HealthCheck {
+  id: string
+  url: string
+  interval: number
+  timeout: number
+  status: 'healthy' | 'unhealthy'
+}
+export declare interface SyntheticMonitor {
+  id: string
+  name: string
+  script: string
+  frequency: number
+  locations: string[]
+}
+export declare interface UptimeTracker {
+  id: string
+  resource: string
+  uptime: number
+  downtime: number
+  availability: number
+}
+export declare class HealthCheckManager {
+  private checks: any;
+  private synthetics: any;
+  private uptimeTrackers: any;
+  private counter: any;
+  createHealthCheck(url: string, interval?: any, timeout?: any): HealthCheck;
+  createSyntheticMonitor(name: string, script: string, frequency: number, locations: string[]): SyntheticMonitor;
+  trackUptime(resource: string, uptime: number, downtime: number): UptimeTracker;
+  clear(): void;
+}