@stacksjs/ts-cloud 0.2.3 → 0.2.5

package/dist/aws/sms.d.ts

@@ -0,0 +1,477 @@
+/**
+ * Unified SMS Module
+ * Provides SMS sending and receiving with S3 storage for incoming messages
+ *
+ * Similar to the Email module, this provides:
+ * - Sending SMS via SNS
+ * - Receiving SMS stored in S3
+ * - Inbox management (list, read, delete)
+ * - Two-way messaging support
+ */
+export interface SmsClientConfig {
+    region?: string;
+    inboxBucket?: string;
+    inboxPrefix?: string;
+    defaultSender?: string;
+    schedulerLambdaArn?: string;
+    schedulerRoleArn?: string;
+    scheduledBucket?: string;
+    scheduledPrefix?: string;
+    receiptBucket?: string;
+    receiptPrefix?: string;
+    trackDelivery?: boolean;
+}
+export interface SmsMessage {
+    key: string;
+    from: string;
+    to: string;
+    body: string;
+    timestamp: Date;
+    messageId?: string;
+    originationNumber?: string;
+    destinationNumber?: string;
+    read?: boolean;
+    readAt?: Date;
+    conversationId?: string;
+    status?: 'pending' | 'sent' | 'delivered' | 'failed';
+    deliveredAt?: Date;
+    raw?: any;
+}
+export interface SendSmsOptions {
+    to: string;
+    body: string;
+    from?: string;
+    type?: 'Promotional' | 'Transactional';
+    scheduledAt?: Date;
+    templateId?: string;
+    templateVariables?: Record<string, string>;
+}
+export interface ScheduledSms {
+    id: string;
+    to: string;
+    body: string;
+    from?: string;
+    scheduledAt: Date;
+    status: 'pending' | 'sent' | 'failed' | 'cancelled';
+    createdAt: Date;
+    sentAt?: Date;
+    messageId?: string;
+    error?: string;
+    templateId?: string;
+    templateVariables?: Record<string, string>;
+}
+export interface SmsTemplate {
+    id: string;
+    name: string;
+    body: string;
+    description?: string;
+    variables?: string[];
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export interface InboxOptions {
+    prefix?: string;
+    maxResults?: number;
+    startAfter?: string;
+}
+export interface DeliveryReceipt {
+    messageId: string;
+    status: 'pending' | 'sent' | 'delivered' | 'failed' | 'unknown';
+    timestamp: Date;
+    to: string;
+    from?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    carrierName?: string;
+    priceInUsd?: number;
+    messagePartCount?: number;
+    raw?: any;
+}
+export interface DeliveryReceiptWebhookConfig {
+    snsTopicArn?: string;
+    receiptBucket?: string;
+    receiptPrefix?: string;
+    webhookUrl?: string;
+    webhookSecret?: string;
+}
+/**
+ * SMS Client with S3 inbox storage
+ */
+export declare class SmsClient {
+    private config;
+    private sns;
+    private s3?;
+    private scheduler?;
+    constructor(config?: SmsClientConfig);
+    /**
+     * Send an SMS message (optionally scheduled)
+     */
+    send(options: SendSmsOptions): Promise<{
+        messageId: string;
+        scheduledId?: string;
+    }>;
+    /**
+     * Send a text message (alias for send)
+     */
+    sendText(to: string, message: string, from?: string): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Get incoming SMS messages from S3 inbox
+     */
+    getInbox(options?: InboxOptions): Promise<SmsMessage[]>;
+    /**
+     * Get a specific SMS message by key
+     */
+    getMessage(key: string): Promise<SmsMessage | null>;
+    /**
+     * Delete an SMS message from inbox
+     */
+    deleteMessage(key: string): Promise<void>;
+    /**
+     * Move an SMS to a different folder (e.g., archive)
+     */
+    moveMessage(key: string, destinationPrefix: string): Promise<string>;
+    /**
+     * Archive an SMS message
+     */
+    archiveMessage(key: string): Promise<string>;
+    /**
+     * Mark a message as read
+     */
+    markAsRead(key: string): Promise<void>;
+    /**
+     * Mark a message as unread
+     */
+    markAsUnread(key: string): Promise<void>;
+    /**
+     * Get unread message count
+     */
+    getUnreadCount(): Promise<number>;
+    /**
+     * Batch mark messages as read
+     */
+    markManyAsRead(keys: string[]): Promise<void>;
+    /**
+     * Batch delete messages
+     */
+    deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Get inbox count
+     */
+    getInboxCount(): Promise<number>;
+    /**
+     * Get conversation ID for a phone number pair
+     * Normalizes phone numbers and creates a consistent ID
+     */
+    getConversationId(phone1: string, phone2: string): string;
+    /**
+     * Get all messages in a conversation with a specific phone number
+     */
+    getConversation(phoneNumber: string, myNumber?: string): Promise<SmsMessage[]>;
+    /**
+     * Get unique conversations (grouped by contact)
+     */
+    getConversations(): Promise<Array<{
+        phoneNumber: string;
+        lastMessage: SmsMessage;
+        messageCount: number;
+        unreadCount: number;
+    }>>;
+    /**
+     * Store an incoming SMS to S3
+     * This is typically called from a Lambda handler that receives SNS webhooks
+     */
+    storeIncomingSms(message: {
+        from: string;
+        to: string;
+        body: string;
+        messageId?: string;
+        timestamp?: Date;
+        raw?: any;
+    }): Promise<string>;
+    /**
+     * Check if a phone number is opted out
+     */
+    isOptedOut(phoneNumber: string): Promise<boolean>;
+    /**
+     * Get list of opted-out phone numbers
+     */
+    getOptedOutNumbers(): Promise<string[]>;
+    /**
+     * Opt a phone number back in (requires user consent)
+     */
+    optIn(phoneNumber: string): Promise<void>;
+    /**
+     * Check if account is in SMS sandbox
+     */
+    isInSandbox(): Promise<boolean>;
+    /**
+     * Add a phone number to SMS sandbox for testing
+     */
+    addSandboxNumber(phoneNumber: string): Promise<void>;
+    /**
+     * Verify a sandbox phone number with OTP
+     */
+    verifySandboxNumber(phoneNumber: string, otp: string): Promise<void>;
+    /**
+     * List sandbox phone numbers
+     */
+    listSandboxNumbers(): Promise<Array<{
+        PhoneNumber: string;
+        Status: string;
+    }>>;
+    /**
+     * Schedule an SMS message for later delivery
+     */
+    scheduleMessage(options: {
+        to: string;
+        body: string;
+        from?: string;
+        scheduledAt: Date;
+        templateId?: string;
+        templateVariables?: Record<string, string>;
+    }): Promise<ScheduledSms>;
+    /**
+     * Get all scheduled SMS messages
+     */
+    getScheduledMessages(): Promise<ScheduledSms[]>;
+    /**
+     * Get a scheduled SMS by ID
+     */
+    getScheduledMessage(id: string): Promise<ScheduledSms | null>;
+    /**
+     * Cancel a scheduled SMS
+     */
+    cancelScheduledMessage(id: string): Promise<void>;
+    /**
+     * Send a scheduled SMS immediately (called by Lambda handler)
+     */
+    sendScheduledMessage(id: string): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Schedule SMS to send at a specific time (convenience method)
+     */
+    sendAt(to: string, body: string, scheduledAt: Date, from?: string): Promise<ScheduledSms>;
+    /**
+     * Schedule SMS to send after a delay (convenience method)
+     */
+    sendAfter(to: string, body: string, delayMinutes: number, from?: string): Promise<ScheduledSms>;
+    /**
+     * Create an SMS template
+     */
+    createTemplate(template: {
+        name: string;
+        body: string;
+        description?: string;
+    }): Promise<SmsTemplate>;
+    /**
+     * Get all SMS templates
+     */
+    getTemplates(): Promise<SmsTemplate[]>;
+    /**
+     * Get a template by ID
+     */
+    getTemplate(id: string): Promise<SmsTemplate | null>;
+    /**
+     * Get a template by name
+     */
+    getTemplateByName(name: string): Promise<SmsTemplate | null>;
+    /**
+     * Update a template
+     */
+    updateTemplate(id: string, updates: {
+        name?: string;
+        body?: string;
+        description?: string;
+    }): Promise<SmsTemplate>;
+    /**
+     * Delete a template
+     */
+    deleteTemplate(id: string): Promise<void>;
+    /**
+     * Send using a template
+     */
+    sendTemplate(to: string, templateId: string, variables: Record<string, string>, from?: string): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Apply variables to a template string
+     */
+    private applyTemplate;
+    /**
+     * Store a delivery receipt
+     * Called by the Lambda handler when a delivery status notification is received
+     */
+    storeDeliveryReceipt(receipt: {
+        messageId: string;
+        status: DeliveryReceipt['status'];
+        to: string;
+        from?: string;
+        errorCode?: string;
+        errorMessage?: string;
+        carrierName?: string;
+        priceInUsd?: number;
+        messagePartCount?: number;
+        timestamp?: Date;
+        raw?: any;
+    }): Promise<string>;
+    /**
+     * Get delivery receipt for a message
+     */
+    getDeliveryReceipt(messageId: string): Promise<DeliveryReceipt | null>;
+    /**
+     * Get all delivery receipts (recent)
+     */
+    getDeliveryReceipts(options?: {
+        maxResults?: number;
+        status?: DeliveryReceipt['status'];
+    }): Promise<DeliveryReceipt[]>;
+    /**
+     * Get delivery status for a message
+     */
+    getDeliveryStatus(messageId: string): Promise<DeliveryReceipt['status']>;
+    /**
+     * Wait for delivery confirmation (polling)
+     */
+    waitForDelivery(messageId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<DeliveryReceipt | null>;
+    /**
+     * Get failed message receipts
+     */
+    getFailedMessages(maxResults?: number): Promise<DeliveryReceipt[]>;
+    /**
+     * Get delivery statistics
+     */
+    getDeliveryStats(options?: {
+        since?: Date;
+        maxMessages?: number;
+    }): Promise<{
+        total: number;
+        delivered: number;
+        failed: number;
+        pending: number;
+        deliveryRate: number;
+        averagePriceUsd: number;
+    }>;
+    /**
+     * Send SMS and track delivery
+     * Combines send() with delivery tracking
+     */
+    sendAndTrack(options: SendSmsOptions): Promise<{
+        messageId: string;
+        trackDelivery: () => Promise<DeliveryReceipt | null>;
+        waitForDelivery: (timeoutMs?: number) => Promise<DeliveryReceipt | null>;
+    }>;
+    /**
+     * Parse incoming SMS from various formats (SNS notification, raw JSON)
+     */
+    private parseIncomingSms;
+    /**
+     * Extract SMS fields from various data formats
+     */
+    private extractSmsFields;
+}
+/**
+ * Create a Lambda handler for processing incoming SMS from SNS
+ * Use this with an SNS topic that receives two-way SMS messages
+ *
+ * @example
+ * ```typescript
+ * // lambda.ts
+ * import { createSmsInboxHandler } from 'ts-cloud/aws/sms'
+ *
+ * export const handler = createSmsInboxHandler({
+ *   bucket: 'my-sms-bucket',
+ *   prefix: 'sms/inbox/',
+ *   region: 'us-east-1',
+ * })
+ * ```
+ */
+export declare function createSmsInboxHandler(config: {
+    bucket: string;
+    prefix?: string;
+    region?: string;
+    onMessage?: (message: SmsMessage) => Promise<void>;
+}): (event: any) => Promise<any>;
+/**
+ * Create a Lambda handler for sending scheduled SMS messages
+ * This is invoked by EventBridge Scheduler at the scheduled time
+ *
+ * @example
+ * ```typescript
+ * // lambda.ts
+ * import { createScheduledSmsHandler } from 'ts-cloud/aws/sms'
+ *
+ * export const handler = createScheduledSmsHandler({
+ *   bucket: 'my-sms-bucket',
+ *   region: 'us-east-1',
+ * })
+ * ```
+ */
+export declare function createScheduledSmsHandler(config: {
+    bucket: string;
+    scheduledPrefix?: string;
+    region?: string;
+    onSent?: (sms: ScheduledSms) => Promise<void>;
+    onError?: (sms: ScheduledSms, error: Error) => Promise<void>;
+}): (event: any) => Promise<any>;
+/**
+ * Convenience function to create an SMS client
+ */
+export declare function createSmsClient(config?: SmsClientConfig): SmsClient;
+/**
+ * Create a Lambda handler for processing SMS delivery receipts
+ * This handles SNS notifications for SMS delivery status events
+ *
+ * @example
+ * ```typescript
+ * // lambda.ts
+ * import { createDeliveryReceiptHandler } from 'ts-cloud/aws/sms'
+ *
+ * export const handler = createDeliveryReceiptHandler({
+ *   bucket: 'my-sms-bucket',
+ *   region: 'us-east-1',
+ *   onDelivered: async (receipt) => {
+ *     console.log(`SMS ${receipt.messageId} delivered to ${receipt.to}`)
+ *   },
+ *   onFailed: async (receipt) => {
+ *     console.error(`SMS ${receipt.messageId} failed: ${receipt.errorMessage}`)
+ *   },
+ * })
+ * ```
+ */
+export declare function createDeliveryReceiptHandler(config: {
+    bucket: string;
+    receiptPrefix?: string;
+    region?: string;
+    onDelivered?: (receipt: DeliveryReceipt) => Promise<void>;
+    onFailed?: (receipt: DeliveryReceipt) => Promise<void>;
+    onReceipt?: (receipt: DeliveryReceipt) => Promise<void>;
+    webhookUrl?: string;
+    webhookSecret?: string;
+}): (event: any) => Promise<any>;
+/**
+ * Normalize a phone number to E.164 format
+ * Removes all non-numeric characters except leading +
+ */
+export declare function normalizePhoneNumber(phone: string): string;
+/**
+ * Format a phone number for display
+ */
+export declare function formatPhoneNumber(phone: string, format?: 'national' | 'international' | 'e164'): string;
+/**
+ * Validate a phone number
+ */
+export declare function isValidPhoneNumber(phone: string): boolean;
+/**
+ * Get the country code from a phone number
+ */
+export declare function getCountryCode(phone: string): string | null;
+/**
+ * Check if two phone numbers are the same (ignoring formatting)
+ */
+export declare function isSamePhoneNumber(phone1: string, phone2: string): boolean;

package/dist/aws/smtp-server.d.ts

@@ -0,0 +1,108 @@
+/**
+ * SMTP Relay Server
+ * Provides SMTP access with user-friendly credentials that relays to AWS SES
+ *
+ * This allows email clients like Mail.app to send emails using:
+ * - Server: mail.yourdomain.com
+ * - Username: chris (or chris@yourdomain.com)
+ * - Password: your-password
+ *
+ * Instead of the unfriendly AWS SES SMTP credentials.
+ */
+export interface SmtpServerConfig {
+    port?: number;
+    tlsPort?: number;
+    host?: string;
+    region?: string;
+    domain: string;
+    users: Record<string, {
+        password: string;
+        email: string;
+    }>;
+    tls?: {
+        key: string;
+        cert: string;
+    };
+    sentBucket?: string;
+    sentPrefix?: string;
+}
+/**
+ * SMTP Server that relays emails through AWS SES
+ */
+export declare class SmtpServer {
+    private config;
+    private ses;
+    private s3?;
+    private server?;
+    private tlsServer?;
+    private sessions;
+    constructor(config: SmtpServerConfig);
+    /**
+     * Start the SMTP server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the SMTP server
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle a new connection
+     */
+    private handleConnection;
+    /**
+     * Send a response to the client
+     */
+    private send;
+    /**
+     * Handle an SMTP command
+     */
+    private handleCommand;
+    /**
+     * Handle EHLO/HELO command
+     */
+    private handleEhlo;
+    /**
+     * Handle STARTTLS command
+     */
+    private handleStartTls;
+    /**
+     * Handle AUTH command
+     */
+    private handleAuth;
+    /**
+     * Handle AUTH PLAIN credentials
+     */
+    private handleAuthPlain;
+    /**
+     * Authenticate a user
+     */
+    private authenticateUser;
+    /**
+     * Handle MAIL FROM command
+     */
+    private handleMailFrom;
+    /**
+     * Handle RCPT TO command
+     */
+    private handleRcptTo;
+    /**
+     * Handle DATA command
+     */
+    private handleData;
+    /**
+     * Handle a line during DATA phase
+     */
+    private handleDataLine;
+    /**
+     * Send the email via SES
+     */
+    private sendEmail;
+    /**
+     * Reset session state for next message
+     */
+    private resetSession;
+}
+/**
+ * Start an SMTP server with the given configuration
+ */
+export declare function startSmtpServer(config: SmtpServerConfig): Promise<SmtpServer>;