@stacksjs/ts-cloud-core 0.1.1

package/src/phone/advanced/recording.ts

@@ -0,0 +1,310 @@
+/**
+ * Call Recording with Transcription
+ *
+ * Provides call recording storage and transcription
+ */
+
+export interface CallRecording {
+  recordingId: string
+  contactId: string
+  startTime: string
+  endTime: string
+  duration: number
+  participants: string[]
+  recordingUrl: string
+  transcription?: CallTranscription
+  status: 'recording' | 'processing' | 'completed' | 'failed'
+  createdAt: string
+}
+
+export interface CallTranscription {
+  transcriptId: string
+  text: string
+  segments: TranscriptionSegment[]
+  language: string
+  confidence: number
+  status: 'pending' | 'processing' | 'completed' | 'failed'
+}
+
+export interface TranscriptionSegment {
+  speaker: string
+  startTime: number
+  endTime: number
+  text: string
+  confidence: number
+  sentiment?: 'positive' | 'neutral' | 'negative'
+}
+
+/**
+ * Call Recording Module
+ */
+export class CallRecording {
+  /**
+   * Lambda code for processing call recordings
+   */
+  static RecordingProcessorCode = `
+const { S3Client, GetObjectCommand, PutObjectCommand, CopyObjectCommand } = require('@aws-sdk/client-s3');
+const { TranscribeClient, StartTranscriptionJobCommand, GetTranscriptionJobCommand } = require('@aws-sdk/client-transcribe');
+const { DynamoDBClient, PutItemCommand, UpdateItemCommand } = require('@aws-sdk/client-dynamodb');
+
+const s3 = new S3Client({});
+const transcribe = new TranscribeClient({});
+const dynamodb = new DynamoDBClient({});
+
+const RECORDING_BUCKET = process.env.RECORDING_BUCKET;
+const RECORDINGS_TABLE = process.env.RECORDINGS_TABLE;
+
+exports.handler = async (event) => {
+  console.log('Recording processor event:', JSON.stringify(event, null, 2));
+
+  for (const record of event.Records) {
+    try {
+      const bucket = record.s3?.bucket?.name || RECORDING_BUCKET;
+      const key = decodeURIComponent(record.s3?.object?.key?.replace(/\\+/g, ' ') || '');
+
+      // Only process audio files
+      if (!key.match(/\\.(wav|mp3|mp4|flac|ogg|webm)$/i)) continue;
+
+      const recordingId = key.split('/').pop().replace(/\\.[^.]+$/, '');
+      const now = new Date().toISOString();
+
+      // Save recording metadata
+      await dynamodb.send(new PutItemCommand({
+        TableName: RECORDINGS_TABLE,
+        Item: {
+          recordingId: { S: recordingId },
+          bucket: { S: bucket },
+          key: { S: key },
+          status: { S: 'processing' },
+          createdAt: { S: now },
+          ttl: { N: String(Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60) },
+        },
+      }));
+
+      // Start transcription job
+      const transcriptionJobName = \`transcribe-\${recordingId}-\${Date.now()}\`;
+      const mediaUri = \`s3://\${bucket}/\${key}\`;
+
+      await transcribe.send(new StartTranscriptionJobCommand({
+        TranscriptionJobName: transcriptionJobName,
+        LanguageCode: 'en-US',
+        MediaFormat: key.split('.').pop().toLowerCase(),
+        Media: { MediaFileUri: mediaUri },
+        OutputBucketName: bucket,
+        OutputKey: \`transcriptions/\${recordingId}.json\`,
+        Settings: {
+          ShowSpeakerLabels: true,
+          MaxSpeakerLabels: 10,
+          ChannelIdentification: false,
+        },
+      }));
+
+      // Update status
+      await dynamodb.send(new UpdateItemCommand({
+        TableName: RECORDINGS_TABLE,
+        Key: { recordingId: { S: recordingId } },
+        UpdateExpression: 'SET transcriptionJobName = :job, #status = :status',
+        ExpressionAttributeNames: { '#status': 'status' },
+        ExpressionAttributeValues: {
+          ':job': { S: transcriptionJobName },
+          ':status': { S: 'transcribing' },
+        },
+      }));
+
+      console.log(\`Started transcription for: \${recordingId}\`);
+    } catch (error) {
+      console.error('Error processing recording:', error);
+    }
+  }
+
+  return { statusCode: 200 };
+};
+`
+
+  /**
+   * Lambda code for transcription completion
+   */
+  static TranscriptionCompleteCode = `
+const { S3Client, GetObjectCommand } = require('@aws-sdk/client-s3');
+const { DynamoDBClient, UpdateItemCommand, QueryCommand } = require('@aws-sdk/client-dynamodb');
+
+const s3 = new S3Client({});
+const dynamodb = new DynamoDBClient({});
+
+const RECORDING_BUCKET = process.env.RECORDING_BUCKET;
+const RECORDINGS_TABLE = process.env.RECORDINGS_TABLE;
+
+exports.handler = async (event) => {
+  console.log('Transcription complete event:', JSON.stringify(event, null, 2));
+
+  const { detail } = event;
+  const jobName = detail?.TranscriptionJobName;
+  const jobStatus = detail?.TranscriptionJobStatus;
+
+  if (!jobName) return { statusCode: 400 };
+
+  // Find recording by job name
+  const queryResult = await dynamodb.send(new QueryCommand({
+    TableName: RECORDINGS_TABLE,
+    IndexName: 'job-index',
+    KeyConditionExpression: 'transcriptionJobName = :job',
+    ExpressionAttributeValues: {
+      ':job': { S: jobName },
+    },
+  }));
+
+  const recording = queryResult.Items?.[0];
+  if (!recording) {
+    console.log('Recording not found for job:', jobName);
+    return { statusCode: 404 };
+  }
+
+  const recordingId = recording.recordingId.S;
+
+  if (jobStatus === 'COMPLETED') {
+    // Get transcription result
+    const transcriptKey = \`transcriptions/\${recordingId}.json\`;
+    const result = await s3.send(new GetObjectCommand({
+      Bucket: RECORDING_BUCKET,
+      Key: transcriptKey,
+    }));
+
+    const transcriptData = JSON.parse(await result.Body.transformToString());
+
+    // Extract segments with speaker labels
+    const segments = [];
+    const items = transcriptData.results?.items || [];
+    let currentSegment = null;
+
+    for (const item of items) {
+      if (item.type === 'pronunciation') {
+        const speaker = item.speaker_label || 'spk_0';
+        const startTime = parseFloat(item.start_time || 0);
+        const endTime = parseFloat(item.end_time || 0);
+        const content = item.alternatives?.[0]?.content || '';
+        const confidence = parseFloat(item.alternatives?.[0]?.confidence || 0);
+
+        if (!currentSegment || currentSegment.speaker !== speaker) {
+          if (currentSegment) segments.push(currentSegment);
+          currentSegment = {
+            speaker,
+            startTime,
+            endTime,
+            text: content,
+            confidence,
+          };
+        } else {
+          currentSegment.endTime = endTime;
+          currentSegment.text += ' ' + content;
+          currentSegment.confidence = (currentSegment.confidence + confidence) / 2;
+        }
+      }
+    }
+    if (currentSegment) segments.push(currentSegment);
+
+    // Update recording with transcription
+    await dynamodb.send(new UpdateItemCommand({
+      TableName: RECORDINGS_TABLE,
+      Key: { recordingId: { S: recordingId } },
+      UpdateExpression: 'SET #status = :status, transcription = :transcript, completedAt = :now',
+      ExpressionAttributeNames: { '#status': 'status' },
+      ExpressionAttributeValues: {
+        ':status': { S: 'completed' },
+        ':transcript': { S: JSON.stringify({
+          text: transcriptData.results?.transcripts?.[0]?.transcript || '',
+          segments,
+          language: 'en-US',
+          confidence: segments.reduce((sum, s) => sum + s.confidence, 0) / segments.length || 0,
+        })},
+        ':now': { S: new Date().toISOString() },
+      },
+    }));
+
+    console.log(\`Transcription completed for: \${recordingId}\`);
+  } else if (jobStatus === 'FAILED') {
+    await dynamodb.send(new UpdateItemCommand({
+      TableName: RECORDINGS_TABLE,
+      Key: { recordingId: { S: recordingId } },
+      UpdateExpression: 'SET #status = :status, error = :error',
+      ExpressionAttributeNames: { '#status': 'status' },
+      ExpressionAttributeValues: {
+        ':status': { S: 'failed' },
+        ':error': { S: detail?.FailureReason || 'Unknown error' },
+      },
+    }));
+  }
+
+  return { statusCode: 200 };
+};
+`
+
+  /**
+   * Create recordings DynamoDB table
+   */
+  static createRecordingsTable(config: { slug: string }): Record<string, any> {
+    return {
+      [`${config.slug}CallRecordingsTable`]: {
+        Type: 'AWS::DynamoDB::Table',
+        Properties: {
+          TableName: `${config.slug}-call-recordings`,
+          BillingMode: 'PAY_PER_REQUEST',
+          AttributeDefinitions: [
+            { AttributeName: 'recordingId', AttributeType: 'S' },
+            { AttributeName: 'transcriptionJobName', AttributeType: 'S' },
+          ],
+          KeySchema: [
+            { AttributeName: 'recordingId', KeyType: 'HASH' },
+          ],
+          GlobalSecondaryIndexes: [
+            {
+              IndexName: 'job-index',
+              KeySchema: [
+                { AttributeName: 'transcriptionJobName', KeyType: 'HASH' },
+              ],
+              Projection: { ProjectionType: 'ALL' },
+            },
+          ],
+          TimeToLiveSpecification: {
+            AttributeName: 'ttl',
+            Enabled: true,
+          },
+        },
+      },
+    }
+  }
+
+  /**
+   * Create recording processor Lambda
+   */
+  static createRecordingProcessorLambda(config: {
+    slug: string
+    roleArn: string
+    recordingBucket: string
+    recordingsTable: string
+  }): Record<string, any> {
+    return {
+      [`${config.slug}RecordingProcessorLambda`]: {
+        Type: 'AWS::Lambda::Function',
+        Properties: {
+          FunctionName: `${config.slug}-recording-processor`,
+          Runtime: 'nodejs20.x',
+          Handler: 'index.handler',
+          Role: config.roleArn,
+          Timeout: 60,
+          MemorySize: 256,
+          Code: {
+            ZipFile: CallRecording.RecordingProcessorCode,
+          },
+          Environment: {
+            Variables: {
+              RECORDING_BUCKET: config.recordingBucket,
+              RECORDINGS_TABLE: config.recordingsTable,
+            },
+          },
+        },
+      },
+    }
+  }
+}
+
+export default CallRecording

package/src/phone/handlers/__tests__/incoming-call.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'bun:test'
+import { handler } from '../incoming-call'
+
+describe('Incoming Call Handler', () => {
+  it('should export handler code as string', () => {
+    expect(typeof handler).toBe('string')
+    expect(handler).toContain('exports.handler')
+  })
+
+  it('should contain SNS client import', () => {
+    expect(handler).toContain('SNSClient')
+    expect(handler).toContain('PublishCommand')
+  })
+
+  it('should contain DynamoDB client import', () => {
+    expect(handler).toContain('DynamoDBClient')
+    expect(handler).toContain('PutItemCommand')
+  })
+
+  it('should extract contact data', () => {
+    expect(handler).toContain('ContactData')
+    expect(handler).toContain('CustomerEndpoint')
+    expect(handler).toContain('SystemEndpoint')
+  })
+
+  it('should log calls to DynamoDB', () => {
+    expect(handler).toContain('CALL_LOG_TABLE')
+    expect(handler).toContain('contactId')
+  })
+
+  it('should send notifications', () => {
+    expect(handler).toContain('NOTIFICATION_TOPIC_ARN')
+    expect(handler).toContain('incoming_call')
+  })
+
+  it('should support webhook notifications', () => {
+    expect(handler).toContain('WEBHOOK_URL')
+    expect(handler).toContain('fetch')
+  })
+})

package/src/phone/handlers/incoming-call.ts

@@ -0,0 +1,117 @@
+/**
+ * Incoming Call Lambda Handler
+ *
+ * Processes incoming calls from Amazon Connect:
+ * - Logs call details
+ * - Sends notifications (SNS, webhook)
+ * - Routes based on caller ID
+ */
+
+export const handler = `
+const { SNSClient, PublishCommand } = require('@aws-sdk/client-sns');
+const { DynamoDBClient, PutItemCommand } = require('@aws-sdk/client-dynamodb');
+
+const sns = new SNSClient({});
+const dynamodb = new DynamoDBClient({});
+
+exports.handler = async (event) => {
+  console.log('Incoming call event:', JSON.stringify(event, null, 2));
+
+  const notificationTopicArn = process.env.NOTIFICATION_TOPIC_ARN;
+  const callLogTable = process.env.CALL_LOG_TABLE;
+  const webhookUrl = process.env.WEBHOOK_URL;
+
+  try {
+    // Extract call details from Connect event
+    const contactData = event.Details?.ContactData || {};
+    const parameters = event.Details?.Parameters || {};
+
+    const callDetails = {
+      contactId: contactData.ContactId,
+      channel: contactData.Channel || 'VOICE',
+      initiationMethod: contactData.InitiationMethod,
+      customerEndpoint: contactData.CustomerEndpoint?.Address,
+      systemEndpoint: contactData.SystemEndpoint?.Address,
+      queue: contactData.Queue?.Name,
+      attributes: contactData.Attributes || {},
+      timestamp: new Date().toISOString(),
+    };
+
+    console.log('Call details:', callDetails);
+
+    // Log call to DynamoDB
+    if (callLogTable) {
+      await dynamodb.send(new PutItemCommand({
+        TableName: callLogTable,
+        Item: {
+          contactId: { S: callDetails.contactId },
+          timestamp: { S: callDetails.timestamp },
+          callerNumber: { S: callDetails.customerEndpoint || 'unknown' },
+          calledNumber: { S: callDetails.systemEndpoint || 'unknown' },
+          channel: { S: callDetails.channel },
+          initiationMethod: { S: callDetails.initiationMethod || 'unknown' },
+          status: { S: 'incoming' },
+          ttl: { N: String(Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60) }, // 90 days
+        },
+      }));
+    }
+
+    // Send SNS notification
+    if (notificationTopicArn) {
+      await sns.send(new PublishCommand({
+        TopicArn: notificationTopicArn,
+        Subject: 'Incoming Call',
+        Message: JSON.stringify({
+          type: 'incoming_call',
+          from: callDetails.customerEndpoint,
+          to: callDetails.systemEndpoint,
+          contactId: callDetails.contactId,
+          timestamp: callDetails.timestamp,
+        }, null, 2),
+        MessageAttributes: {
+          eventType: {
+            DataType: 'String',
+            StringValue: 'incoming_call',
+          },
+        },
+      }));
+    }
+
+    // Send webhook notification
+    if (webhookUrl) {
+      try {
+        await fetch(webhookUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            event: 'incoming_call',
+            data: callDetails,
+          }),
+        });
+      } catch (err) {
+        console.error('Webhook notification failed:', err.message);
+      }
+    }
+
+    // Return routing decision
+    // Can be customized based on caller ID, time of day, etc.
+    return {
+      statusCode: 200,
+      route: parameters.defaultRoute || 'main_queue',
+      callerInfo: {
+        number: callDetails.customerEndpoint,
+        isKnown: false, // Could lookup in CRM
+      },
+    };
+
+  } catch (error) {
+    console.error('Error processing incoming call:', error);
+    return {
+      statusCode: 500,
+      error: error.message,
+    };
+  }
+};
+`
+
+export default handler

package/src/phone/handlers/missed-call.ts

@@ -0,0 +1,116 @@
+/**
+ * Missed Call Lambda Handler
+ *
+ * Processes missed call events:
+ * - Logs missed call
+ * - Sends notification
+ */
+
+export const handler = `
+const { SNSClient, PublishCommand } = require('@aws-sdk/client-sns');
+const { DynamoDBClient, UpdateItemCommand } = require('@aws-sdk/client-dynamodb');
+
+const sns = new SNSClient({});
+const dynamodb = new DynamoDBClient({});
+
+exports.handler = async (event) => {
+  console.log('Missed call event:', JSON.stringify(event, null, 2));
+
+  const notificationTopicArn = process.env.NOTIFICATION_TOPIC_ARN;
+  const callLogTable = process.env.CALL_LOG_TABLE;
+  const webhookUrl = process.env.WEBHOOK_URL;
+
+  try {
+    // Extract call details from Connect event
+    const contactData = event.Details?.ContactData || {};
+
+    const callDetails = {
+      contactId: contactData.ContactId,
+      customerEndpoint: contactData.CustomerEndpoint?.Address,
+      systemEndpoint: contactData.SystemEndpoint?.Address,
+      queue: contactData.Queue?.Name,
+      waitTime: contactData.Queue?.EnqueueTimestamp
+        ? Math.floor((Date.now() - new Date(contactData.Queue.EnqueueTimestamp).getTime()) / 1000)
+        : 0,
+      disconnectReason: event.Details?.Parameters?.disconnectReason || 'customer_abandoned',
+      timestamp: new Date().toISOString(),
+    };
+
+    console.log('Missed call details:', callDetails);
+
+    // Update call log
+    if (callLogTable && callDetails.contactId) {
+      await dynamodb.send(new UpdateItemCommand({
+        TableName: callLogTable,
+        Key: {
+          contactId: { S: callDetails.contactId },
+        },
+        UpdateExpression: 'SET #status = :status, disconnectReason = :reason, waitTime = :wait, missedAt = :at',
+        ExpressionAttributeNames: {
+          '#status': 'status',
+        },
+        ExpressionAttributeValues: {
+          ':status': { S: 'missed' },
+          ':reason': { S: callDetails.disconnectReason },
+          ':wait': { N: String(callDetails.waitTime) },
+          ':at': { S: callDetails.timestamp },
+        },
+      }));
+    }
+
+    // Send SNS notification
+    if (notificationTopicArn) {
+      await sns.send(new PublishCommand({
+        TopicArn: notificationTopicArn,
+        Subject: 'Missed Call Alert',
+        Message: JSON.stringify({
+          type: 'missed_call',
+          from: callDetails.customerEndpoint,
+          to: callDetails.systemEndpoint,
+          queue: callDetails.queue,
+          waitTime: callDetails.waitTime,
+          reason: callDetails.disconnectReason,
+          contactId: callDetails.contactId,
+          timestamp: callDetails.timestamp,
+        }, null, 2),
+        MessageAttributes: {
+          eventType: {
+            DataType: 'String',
+            StringValue: 'missed_call',
+          },
+        },
+      }));
+    }
+
+    // Send webhook notification
+    if (webhookUrl) {
+      try {
+        await fetch(webhookUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            event: 'missed_call',
+            data: callDetails,
+          }),
+        });
+      } catch (err) {
+        console.error('Webhook notification failed:', err.message);
+      }
+    }
+
+    return {
+      statusCode: 200,
+      message: 'Missed call logged',
+    };
+
+  } catch (error) {
+    console.error('Error processing missed call:', error);
+    return {
+      statusCode: 500,
+      error: error.message,
+    };
+  }
+};
+`
+
+export default handler