@stacksjs/ts-cloud-core 0.1.8 → 0.1.9

package/src/sms/advanced/mms.ts

@@ -0,0 +1,308 @@
+/**
+ * MMS Support (Images, Media)
+ *
+ * Provides multimedia messaging capabilities
+ */
+
+export interface MmsMessage {
+  to: string
+  body?: string
+  mediaUrls: string[]
+  mediaType?: 'image' | 'video' | 'audio' | 'document'
+  fallbackSms?: string
+}
+
+export interface MmsMedia {
+  url: string
+  contentType: string
+  size: number
+  filename?: string
+}
+
+/**
+ * MMS Module
+ */
+export class MmsSupport {
+  /**
+   * Lambda code for MMS sending
+   */
+  static MmsSenderCode = `
+const { S3Client, PutObjectCommand, GetObjectCommand } = require('@aws-sdk/client-s3');
+const { SNSClient, PublishCommand } = require('@aws-sdk/client-sns');
+const { DynamoDBClient, PutItemCommand } = require('@aws-sdk/client-dynamodb');
+
+const s3 = new S3Client({});
+const sns = new SNSClient({});
+const dynamodb = new DynamoDBClient({});
+
+const MEDIA_BUCKET = process.env.MEDIA_BUCKET;
+const MESSAGE_LOG_TABLE = process.env.MESSAGE_LOG_TABLE;
+const ORIGINATION_NUMBER = process.env.ORIGINATION_NUMBER;
+
+// Supported media types
+const SUPPORTED_TYPES = {
+  'image/jpeg': { maxSize: 1024 * 1024, extension: 'jpg' },
+  'image/png': { maxSize: 1024 * 1024, extension: 'png' },
+  'image/gif': { maxSize: 1024 * 1024, extension: 'gif' },
+  'video/mp4': { maxSize: 5 * 1024 * 1024, extension: 'mp4' },
+  'video/3gpp': { maxSize: 5 * 1024 * 1024, extension: '3gp' },
+  'audio/mpeg': { maxSize: 1024 * 1024, extension: 'mp3' },
+  'audio/wav': { maxSize: 1024 * 1024, extension: 'wav' },
+};
+
+exports.handler = async (event) => {
+  console.log('MMS sender event:', JSON.stringify(event, null, 2));
+
+  try {
+    const body = JSON.parse(event.body || '{}');
+    const { to, text, mediaUrls, fallbackSms } = body;
+
+    if (!to) {
+      return {
+        statusCode: 400,
+        body: JSON.stringify({ error: 'Missing recipient phone number' }),
+      };
+    }
+
+    if (!mediaUrls || mediaUrls.length === 0) {
+      return {
+        statusCode: 400,
+        body: JSON.stringify({ error: 'At least one media URL is required' }),
+      };
+    }
+
+    const messageId = \`mms-\${Date.now()}-\${Math.random().toString(36).substr(2, 9)}\`;
+    const now = new Date().toISOString();
+
+    // Validate and process media
+    const processedMedia = [];
+    for (const url of mediaUrls) {
+      try {
+        const media = await processMedia(url, messageId);
+        processedMedia.push(media);
+      } catch (error) {
+        console.error(\`Failed to process media \${url}:\`, error);
+      }
+    }
+
+    if (processedMedia.length === 0) {
+      // Fall back to SMS if no media could be processed
+      if (fallbackSms) {
+        const smsResult = await sendFallbackSms(to, fallbackSms);
+        return {
+          statusCode: 200,
+          body: JSON.stringify({
+            messageId,
+            type: 'sms_fallback',
+            ...smsResult,
+          }),
+        };
+      }
+      return {
+        statusCode: 400,
+        body: JSON.stringify({ error: 'No valid media could be processed' }),
+      };
+    }
+
+    // Send MMS via SNS (carrier-dependent)
+    // Note: True MMS requires carrier integration or third-party service
+    // This implementation uses SNS with media URLs as a simplified approach
+    const message = {
+      to,
+      text: text || '',
+      mediaUrls: processedMedia.map(m => m.publicUrl),
+      messageId,
+      timestamp: now,
+    };
+
+    const snsResult = await sns.send(new PublishCommand({
+      PhoneNumber: to,
+      Message: text || 'You have received a multimedia message. View it here: ' + processedMedia[0].publicUrl,
+      MessageAttributes: {
+        'AWS.SNS.SMS.SMSType': {
+          DataType: 'String',
+          StringValue: 'Transactional',
+        },
+      },
+    }));
+
+    // Log message
+    await dynamodb.send(new PutItemCommand({
+      TableName: MESSAGE_LOG_TABLE,
+      Item: {
+        messageId: { S: messageId },
+        type: { S: 'mms' },
+        to: { S: to },
+        text: { S: text || '' },
+        mediaUrls: { SS: processedMedia.map(m => m.publicUrl) },
+        snsMessageId: { S: snsResult.MessageId || '' },
+        sentAt: { S: now },
+        ttl: { N: String(Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60) },
+      },
+    }));
+
+    return {
+      statusCode: 200,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        messageId,
+        type: 'mms',
+        mediaCount: processedMedia.length,
+        snsMessageId: snsResult.MessageId,
+      }),
+    };
+  } catch (error) {
+    console.error('Error sending MMS:', error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: error.message }),
+    };
+  }
+};
+
+async function processMedia(url, messageId) {
+  // Fetch media
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(\`Failed to fetch media: \${response.status}\`);
+  }
+
+  const contentType = response.headers.get('content-type') || 'application/octet-stream';
+  const typeConfig = SUPPORTED_TYPES[contentType];
+
+  if (!typeConfig) {
+    throw new Error(\`Unsupported media type: \${contentType}\`);
+  }
+
+  const buffer = await response.arrayBuffer();
+  if (buffer.byteLength > typeConfig.maxSize) {
+    throw new Error(\`Media too large: \${buffer.byteLength} bytes (max: \${typeConfig.maxSize})\`);
+  }
+
+  // Upload to S3
+  const key = \`mms/\${messageId}/media.\${typeConfig.extension}\`;
+  await s3.send(new PutObjectCommand({
+    Bucket: MEDIA_BUCKET,
+    Key: key,
+    Body: Buffer.from(buffer),
+    ContentType: contentType,
+  }));
+
+  // Generate public URL (requires bucket to be configured for public access or use presigned URL)
+  const publicUrl = \`https://\${MEDIA_BUCKET}.s3.amazonaws.com/\${key}\`;
+
+  return {
+    originalUrl: url,
+    publicUrl,
+    contentType,
+    size: buffer.byteLength,
+  };
+}
+
+async function sendFallbackSms(to, message) {
+  const result = await sns.send(new PublishCommand({
+    PhoneNumber: to,
+    Message: message,
+    MessageAttributes: {
+      'AWS.SNS.SMS.SMSType': {
+        DataType: 'String',
+        StringValue: 'Transactional',
+      },
+    },
+  }));
+
+  return {
+    snsMessageId: result.MessageId,
+    fallback: true,
+  };
+}
+`
+
+  /**
+   * Create media storage bucket
+   */
+  static createMediaBucket(config: { slug: string }): Record<string, any> {
+    return {
+      [`${config.slug}MmsMediaBucket`]: {
+        Type: 'AWS::S3::Bucket',
+        Properties: {
+          BucketName: `${config.slug}-mms-media`,
+          LifecycleConfiguration: {
+            Rules: [
+              {
+                Id: 'DeleteOldMedia',
+                Status: 'Enabled',
+                ExpirationInDays: 30,
+              },
+            ],
+          },
+          CorsConfiguration: {
+            CorsRules: [
+              {
+                AllowedOrigins: ['*'],
+                AllowedMethods: ['GET'],
+                AllowedHeaders: ['*'],
+                MaxAge: 3600,
+              },
+            ],
+          },
+        },
+      },
+    }
+  }
+
+  /**
+   * Create MMS sender Lambda
+   */
+  static createMmsSenderLambda(config: {
+    slug: string
+    roleArn: string
+    mediaBucket: string
+    messageLogTable: string
+    originationNumber?: string
+  }): Record<string, any> {
+    return {
+      [`${config.slug}MmsSenderLambda`]: {
+        Type: 'AWS::Lambda::Function',
+        Properties: {
+          FunctionName: `${config.slug}-mms-sender`,
+          Runtime: 'nodejs20.x',
+          Handler: 'index.handler',
+          Role: config.roleArn,
+          Timeout: 60,
+          MemorySize: 512,
+          Code: {
+            ZipFile: MmsSupport.MmsSenderCode,
+          },
+          Environment: {
+            Variables: {
+              MEDIA_BUCKET: config.mediaBucket,
+              MESSAGE_LOG_TABLE: config.messageLogTable,
+              ORIGINATION_NUMBER: config.originationNumber || '',
+            },
+          },
+        },
+      },
+    }
+  }
+
+  /**
+   * Supported media types
+   */
+  static readonly SupportedMediaTypes = {
+    image: ['image/jpeg', 'image/png', 'image/gif'],
+    video: ['video/mp4', 'video/3gpp'],
+    audio: ['audio/mpeg', 'audio/wav'],
+  } as const
+
+  /**
+   * Media size limits (in bytes)
+   */
+  static readonly MediaSizeLimits: { image: number, video: number, audio: number } = {
+    image: 1024 * 1024, // 1MB
+    video: 5 * 1024 * 1024, // 5MB
+    audio: 1024 * 1024, // 1MB
+  }
+}
+
+export default MmsSupport

package/src/sms/handlers/__tests__/send.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'bun:test'
+import { handler } from '../send'
+
+describe('SMS Send Handler', () => {
+  it('should export handler code as string', () => {
+    expect(typeof handler).toBe('string')
+    expect(handler).toContain('exports.handler')
+  })
+
+  it('should contain Pinpoint client import', () => {
+    expect(handler).toContain('PinpointClient')
+    expect(handler).toContain('SendMessagesCommand')
+  })
+
+  it('should contain SNS client as fallback', () => {
+    expect(handler).toContain('SNSClient')
+    expect(handler).toContain('PublishCommand')
+  })
+
+  it('should support templated messages', () => {
+    expect(handler).toContain('template')
+    expect(handler).toContain('templateData')
+    expect(handler).toContain('resolveTemplate')
+  })
+
+  it('should log messages to DynamoDB', () => {
+    expect(handler).toContain('MESSAGE_LOG_TABLE')
+    expect(handler).toContain('messageId')
+  })
+
+  it('should support message types', () => {
+    expect(handler).toContain('TRANSACTIONAL')
+    expect(handler).toContain('PROMOTIONAL')
+  })
+
+  it('should handle delivery status', () => {
+    expect(handler).toContain('DeliveryStatus')
+    expect(handler).toContain('SENT')
+  })
+})

package/src/sms/handlers/delivery-status.ts

@@ -0,0 +1,133 @@
+/**
+ * SMS Delivery Status Lambda Handler
+ *
+ * Processes delivery status updates:
+ * - Process delivery receipts
+ * - Update message status
+ * - Handle failures
+ */
+
+export const handler = `
+const { DynamoDBClient, UpdateItemCommand } = require('@aws-sdk/client-dynamodb');
+const { SNSClient, PublishCommand } = require('@aws-sdk/client-sns');
+
+const dynamodb = new DynamoDBClient({});
+const sns = new SNSClient({});
+
+exports.handler = async (event) => {
+  console.log('SMS delivery status event:', JSON.stringify(event, null, 2));
+
+  const messageLogTable = process.env.MESSAGE_LOG_TABLE;
+  const notificationTopicArn = process.env.NOTIFICATION_TOPIC_ARN;
+  const webhookUrl = process.env.WEBHOOK_URL;
+
+  for (const record of event.Records) {
+    try {
+      // Parse delivery status from SNS/Pinpoint
+      const message = JSON.parse(record.Sns?.Message || record.body || '{}');
+
+      const {
+        eventType,
+        messageId,
+        destinationPhoneNumber,
+        messageStatus,
+        messageStatusDescription,
+        isoCountryCode,
+        mcc,
+        mnc,
+        priceInMillicentsUSD,
+      } = message;
+
+      if (!messageId) {
+        console.log('No messageId in delivery status');
+        continue;
+      }
+
+      const timestamp = new Date().toISOString();
+      const status = messageStatus || eventType || 'UNKNOWN';
+
+      console.log(\`Delivery status for \${messageId}: \${status}\`);
+
+      // Update message log
+      if (messageLogTable) {
+        await dynamodb.send(new UpdateItemCommand({
+          TableName: messageLogTable,
+          Key: {
+            messageId: { S: messageId },
+          },
+          UpdateExpression: 'SET deliveryStatus = :status, statusDescription = :desc, deliveredAt = :at, priceMillicents = :price, countryCode = :country',
+          ExpressionAttributeValues: {
+            ':status': { S: status },
+            ':desc': { S: messageStatusDescription || '' },
+            ':at': { S: timestamp },
+            ':price': { N: String(priceInMillicentsUSD || 0) },
+            ':country': { S: isoCountryCode || '' },
+          },
+        }));
+      }
+
+      // Handle failures - notify admin
+      const isFailure = ['FAILED', 'UNREACHABLE', 'UNKNOWN', 'CARRIER_UNREACHABLE', 'BLOCKED', 'CARRIER_BLOCKED', 'INVALID', 'INVALID_MESSAGE', 'OPTED_OUT'].includes(status);
+
+      if (isFailure) {
+        console.log(\`SMS delivery failed: \${status} - \${messageStatusDescription}\`);
+
+        // Send failure notification
+        if (notificationTopicArn) {
+          await sns.send(new PublishCommand({
+            TopicArn: notificationTopicArn,
+            Subject: \`SMS Delivery Failed: \${status}\`,
+            Message: JSON.stringify({
+              type: 'sms_delivery_failed',
+              messageId,
+              to: destinationPhoneNumber,
+              status,
+              description: messageStatusDescription,
+              countryCode: isoCountryCode,
+              timestamp,
+            }, null, 2),
+            MessageAttributes: {
+              eventType: {
+                DataType: 'String',
+                StringValue: 'sms_delivery_failed',
+              },
+            },
+          }));
+        }
+      }
+
+      // Forward to webhook for all status updates
+      if (webhookUrl) {
+        try {
+          await fetch(webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              event: 'sms_delivery_status',
+              data: {
+                messageId,
+                to: destinationPhoneNumber,
+                status,
+                description: messageStatusDescription,
+                countryCode: isoCountryCode,
+                carrier: { mcc, mnc },
+                priceMillicents: priceInMillicentsUSD,
+                timestamp,
+              },
+            }),
+          });
+        } catch (err) {
+          console.error('Webhook failed:', err.message);
+        }
+      }
+
+    } catch (error) {
+      console.error('Error processing delivery status:', error);
+    }
+  }
+
+  return { statusCode: 200, body: 'OK' };
+};
+`
+
+export default handler

package/src/sms/handlers/receive.ts

@@ -0,0 +1,162 @@
+/**
+ * SMS Receive Lambda Handler
+ *
+ * Processes inbound SMS messages:
+ * - Process inbound SMS (two-way)
+ * - Handle opt-out keywords
+ * - Forward to webhook
+ */
+
+export const handler = `
+const { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand } = require('@aws-sdk/client-dynamodb');
+const { SNSClient, PublishCommand } = require('@aws-sdk/client-sns');
+
+const dynamodb = new DynamoDBClient({});
+const sns = new SNSClient({});
+
+const OPT_OUT_KEYWORDS = ['STOP', 'UNSUBSCRIBE', 'CANCEL', 'END', 'QUIT', 'OPTOUT', 'OPT OUT'];
+const OPT_IN_KEYWORDS = ['START', 'SUBSCRIBE', 'OPTIN', 'OPT IN', 'YES'];
+
+exports.handler = async (event) => {
+  console.log('SMS receive event:', JSON.stringify(event, null, 2));
+
+  const optOutTable = process.env.OPT_OUT_TABLE;
+  const messageLogTable = process.env.MESSAGE_LOG_TABLE;
+  const notificationTopicArn = process.env.NOTIFICATION_TOPIC_ARN;
+  const webhookUrl = process.env.WEBHOOK_URL;
+
+  for (const record of event.Records) {
+    try {
+      // Parse SNS message from Pinpoint
+      const message = JSON.parse(record.Sns?.Message || record.body || '{}');
+
+      const {
+        originationNumber,
+        destinationNumber,
+        messageBody,
+        messageKeyword,
+        inboundMessageId,
+      } = message;
+
+      if (!originationNumber || !messageBody) {
+        console.log('Missing required fields');
+        continue;
+      }
+
+      const timestamp = new Date().toISOString();
+      const normalizedBody = messageBody.trim().toUpperCase();
+
+      // Check for opt-out keywords
+      if (OPT_OUT_KEYWORDS.some(kw => normalizedBody === kw || normalizedBody.startsWith(kw + ' '))) {
+        console.log(\`Opt-out request from \${originationNumber}\`);
+
+        if (optOutTable) {
+          await dynamodb.send(new PutItemCommand({
+            TableName: optOutTable,
+            Item: {
+              phoneNumber: { S: originationNumber },
+              optedOutAt: { S: timestamp },
+              keyword: { S: normalizedBody.split(' ')[0] },
+              originalMessage: { S: messageBody },
+            },
+          }));
+        }
+
+        // Send confirmation (optional - check carrier requirements)
+        // await sendOptOutConfirmation(originationNumber, destinationNumber);
+
+        continue;
+      }
+
+      // Check for opt-in keywords
+      if (OPT_IN_KEYWORDS.some(kw => normalizedBody === kw || normalizedBody.startsWith(kw + ' '))) {
+        console.log(\`Opt-in request from \${originationNumber}\`);
+
+        if (optOutTable) {
+          await dynamodb.send(new DeleteItemCommand({
+            TableName: optOutTable,
+            Key: {
+              phoneNumber: { S: originationNumber },
+            },
+          }));
+        }
+
+        continue;
+      }
+
+      // Log inbound message
+      if (messageLogTable) {
+        await dynamodb.send(new PutItemCommand({
+          TableName: messageLogTable,
+          Item: {
+            messageId: { S: inboundMessageId || \`inbound-\${Date.now()}\` },
+            direction: { S: 'inbound' },
+            from: { S: originationNumber },
+            to: { S: destinationNumber },
+            body: { S: messageBody },
+            keyword: { S: messageKeyword || '' },
+            receivedAt: { S: timestamp },
+            ttl: { N: String(Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60) },
+          },
+        }));
+      }
+
+      // Send SNS notification
+      if (notificationTopicArn) {
+        await sns.send(new PublishCommand({
+          TopicArn: notificationTopicArn,
+          Subject: 'Inbound SMS',
+          Message: JSON.stringify({
+            type: 'inbound_sms',
+            from: originationNumber,
+            to: destinationNumber,
+            body: messageBody,
+            keyword: messageKeyword,
+            timestamp,
+          }, null, 2),
+          MessageAttributes: {
+            eventType: {
+              DataType: 'String',
+              StringValue: 'inbound_sms',
+            },
+          },
+        }));
+      }
+
+      // Forward to webhook
+      if (webhookUrl) {
+        try {
+          const response = await fetch(webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              event: 'inbound_sms',
+              data: {
+                from: originationNumber,
+                to: destinationNumber,
+                body: messageBody,
+                keyword: messageKeyword,
+                messageId: inboundMessageId,
+                timestamp,
+              },
+            }),
+          });
+
+          console.log(\`Webhook response: \${response.status}\`);
+        } catch (err) {
+          console.error('Webhook failed:', err.message);
+        }
+      }
+
+      console.log(\`Processed inbound SMS from \${originationNumber}\`);
+
+    } catch (error) {
+      console.error('Error processing inbound SMS:', error);
+    }
+  }
+
+  return { statusCode: 200, body: 'OK' };
+};
+`
+
+export default handler