@stacksjs/ts-cloud 0.2.3 → 0.2.5

package/dist/aws/voice.d.ts

@@ -0,0 +1,361 @@
+/**
+ * Unified Voice Module
+ * Provides voice calling and voicemail with S3 storage
+ *
+ * Similar to the Email and SMS modules, this provides:
+ * - Making outbound calls via Connect
+ * - Receiving voicemails stored in S3
+ * - Voicemail management (list, read, delete)
+ * - Call recording storage
+ * - Text-to-speech for voice messages
+ */
+export interface VoiceClientConfig {
+    region?: string;
+    voicemailBucket?: string;
+    voicemailPrefix?: string;
+    recordingsPrefix?: string;
+    connectInstanceId?: string;
+    connectContactFlowId?: string;
+    defaultCallerId?: string;
+    enableTranscription?: boolean;
+    transcriptionLanguage?: string;
+}
+export interface Voicemail {
+    key: string;
+    from: string;
+    to: string;
+    duration: number;
+    timestamp: Date;
+    transcription?: string;
+    transcriptionStatus?: 'pending' | 'processing' | 'completed' | 'failed';
+    transcriptionJobName?: string;
+    audioUrl?: string;
+    read?: boolean;
+    readAt?: Date;
+    contentType?: string;
+    size?: number;
+    raw?: any;
+}
+export interface CallRecording {
+    key: string;
+    contactId: string;
+    from?: string;
+    to?: string;
+    duration: number;
+    timestamp: Date;
+    audioUrl?: string;
+    contentType?: string;
+    size?: number;
+}
+export interface MakeCallOptions {
+    to: string;
+    from?: string;
+    message?: string;
+    voiceId?: string;
+    audioUrl?: string;
+    contactFlowId?: string;
+    attributes?: Record<string, string>;
+}
+export interface SendVoiceMessageOptions {
+    to: string;
+    from?: string;
+    message: string;
+    voiceId?: string;
+    languageCode?: string;
+}
+export interface VoicemailGreeting {
+    id: string;
+    name: string;
+    type: 'default' | 'busy' | 'unavailable' | 'custom';
+    text?: string;
+    audioKey?: string;
+    audioUrl?: string;
+    voiceId?: string;
+    languageCode?: string;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export interface CallForwardingRule {
+    id: string;
+    name: string;
+    enabled: boolean;
+    condition: 'always' | 'busy' | 'no_answer' | 'unreachable' | 'after_hours';
+    forwardTo: string;
+    ringTimeout?: number;
+    businessHours?: {
+        timezone: string;
+        schedule: Array<{
+            day: 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+            start: string;
+            end: string;
+        }>;
+    };
+    priority: number;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+/**
+ * Voice Client with S3 voicemail storage
+ */
+export declare class VoiceClient {
+    private config;
+    private connect?;
+    private s3?;
+    private transcribe?;
+    constructor(config?: VoiceClientConfig);
+    /**
+     * Make an outbound voice call via Connect
+     */
+    call(options: MakeCallOptions): Promise<{
+        callId: string;
+    }>;
+    /**
+     * Send a voice message (one-way TTS call) via Connect
+     *
+     * Note: This requires a Contact Flow configured for TTS playback.
+     * The message is passed as an attribute that the Contact Flow can use.
+     */
+    sendVoiceMessage(options: SendVoiceMessageOptions): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Send a TTS voice message (alias for sendVoiceMessage)
+     */
+    speak(to: string, message: string, voiceId?: string): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * Get voicemails from S3
+     */
+    getVoicemails(options?: {
+        prefix?: string;
+        maxResults?: number;
+    }): Promise<Voicemail[]>;
+    /**
+     * Get a specific voicemail
+     */
+    getVoicemail(key: string): Promise<Voicemail | null>;
+    /**
+     * Get voicemail audio as a signed URL
+     */
+    getVoicemailAudioUrl(key: string, expiresIn?: number): Promise<string>;
+    /**
+     * Delete a voicemail
+     */
+    deleteVoicemail(key: string): Promise<void>;
+    /**
+     * Archive a voicemail
+     */
+    archiveVoicemail(key: string): Promise<string>;
+    /**
+     * Get voicemail count
+     */
+    getVoicemailCount(): Promise<number>;
+    /**
+     * Get unread voicemail count
+     */
+    getUnreadCount(): Promise<number>;
+    /**
+     * Mark a voicemail as read
+     */
+    markAsRead(key: string): Promise<void>;
+    /**
+     * Mark a voicemail as unread
+     */
+    markAsUnread(key: string): Promise<void>;
+    /**
+     * Batch mark voicemails as read
+     */
+    markManyAsRead(keys: string[]): Promise<void>;
+    /**
+     * Batch delete voicemails
+     */
+    deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Start transcription for a voicemail
+     */
+    transcribeVoicemail(key: string): Promise<{
+        jobName: string;
+    }>;
+    /**
+     * Get transcription status for a voicemail
+     */
+    getTranscriptionStatus(jobName: string): Promise<{
+        status: 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
+        transcription?: string;
+    }>;
+    /**
+     * Update voicemail metadata with completed transcription
+     */
+    updateTranscription(key: string, transcription: string): Promise<void>;
+    /**
+     * Create a voicemail greeting
+     */
+    createGreeting(greeting: {
+        name: string;
+        type: 'default' | 'busy' | 'unavailable' | 'custom';
+        text?: string;
+        audioData?: Buffer | string;
+        voiceId?: string;
+        languageCode?: string;
+        setActive?: boolean;
+    }): Promise<VoicemailGreeting>;
+    /**
+     * Get all voicemail greetings
+     */
+    getGreetings(): Promise<VoicemailGreeting[]>;
+    /**
+     * Get a specific greeting
+     */
+    getGreeting(id: string): Promise<VoicemailGreeting | null>;
+    /**
+     * Get the active greeting of a specific type
+     */
+    getActiveGreeting(type: 'default' | 'busy' | 'unavailable' | 'custom'): Promise<VoicemailGreeting | null>;
+    /**
+     * Set a greeting as active
+     */
+    setActiveGreeting(id: string): Promise<void>;
+    /**
+     * Deactivate all greetings of a type
+     */
+    private deactivateGreetingsOfType;
+    /**
+     * Update a greeting
+     */
+    updateGreeting(id: string, updates: {
+        name?: string;
+        text?: string;
+        audioData?: Buffer | string;
+    }): Promise<VoicemailGreeting>;
+    /**
+     * Delete a greeting
+     */
+    deleteGreeting(id: string): Promise<void>;
+    /**
+     * Get a signed URL for a greeting audio
+     */
+    getGreetingAudioUrl(id: string, expiresIn?: number): Promise<string | null>;
+    /**
+     * Create a call forwarding rule
+     */
+    createForwardingRule(rule: {
+        name: string;
+        condition: 'always' | 'busy' | 'no_answer' | 'unreachable' | 'after_hours';
+        forwardTo: string;
+        ringTimeout?: number;
+        businessHours?: CallForwardingRule['businessHours'];
+        priority?: number;
+        enabled?: boolean;
+    }): Promise<CallForwardingRule>;
+    /**
+     * Get all forwarding rules
+     */
+    getForwardingRules(): Promise<CallForwardingRule[]>;
+    /**
+     * Get a specific forwarding rule
+     */
+    getForwardingRule(id: string): Promise<CallForwardingRule | null>;
+    /**
+     * Update a forwarding rule
+     */
+    updateForwardingRule(id: string, updates: Partial<Omit<CallForwardingRule, 'id' | 'createdAt' | 'updatedAt'>>): Promise<CallForwardingRule>;
+    /**
+     * Enable/disable a forwarding rule
+     */
+    setForwardingRuleEnabled(id: string, enabled: boolean): Promise<void>;
+    /**
+     * Delete a forwarding rule
+     */
+    deleteForwardingRule(id: string): Promise<void>;
+    /**
+     * Get the applicable forwarding rule for current conditions
+     * Returns the highest priority enabled rule that matches current conditions
+     */
+    getApplicableForwardingRule(currentConditions?: {
+        isBusy?: boolean;
+        isUnreachable?: boolean;
+        noAnswer?: boolean;
+    }): Promise<CallForwardingRule | null>;
+    /**
+     * Check if a time is within business hours
+     */
+    private isWithinBusinessHours;
+    /**
+     * Get call recordings from S3
+     */
+    getRecordings(options?: {
+        prefix?: string;
+        maxResults?: number;
+    }): Promise<CallRecording[]>;
+    /**
+     * Get a recording audio URL
+     */
+    getRecordingUrl(key: string, expiresIn?: number): Promise<string>;
+    /**
+     * Store an incoming voicemail to S3
+     * This is typically called from a Lambda handler
+     */
+    storeVoicemail(voicemail: {
+        from: string;
+        to: string;
+        audioData: Buffer | string;
+        duration?: number;
+        transcription?: string;
+        contentType?: string;
+        timestamp?: Date;
+    }): Promise<string>;
+    /**
+     * Store a call recording to S3
+     */
+    storeRecording(recording: {
+        contactId: string;
+        from?: string;
+        to?: string;
+        audioData: Buffer | string;
+        duration?: number;
+        contentType?: string;
+        timestamp?: Date;
+    }): Promise<string>;
+    /**
+     * Get voicemail metadata from S3
+     */
+    private getVoicemailMetadata;
+}
+/**
+ * Create a Lambda handler for processing incoming voicemails
+ * Use this with Connect's voicemail feature or custom IVR
+ *
+ * @example
+ * ```typescript
+ * // lambda.ts
+ * import { createVoicemailHandler } from 'ts-cloud/aws/voice'
+ *
+ * export const handler = createVoicemailHandler({
+ *   bucket: 'my-voicemail-bucket',
+ *   prefix: 'voicemail/',
+ *   region: 'us-east-1',
+ * })
+ * ```
+ */
+export declare function createVoicemailHandler(config: {
+    bucket: string;
+    prefix?: string;
+    region?: string;
+    onVoicemail?: (voicemail: Voicemail) => Promise<void>;
+}): (event: any) => Promise<any>;
+/**
+ * Create a Lambda handler for Connect recording events
+ * This processes call recordings uploaded to S3 by Connect
+ */
+export declare function createRecordingHandler(config: {
+    bucket: string;
+    prefix?: string;
+    region?: string;
+    onRecording?: (recording: CallRecording) => Promise<void>;
+}): (event: any) => Promise<any>;
+/**
+ * Convenience function to create a voice client
+ */
+export declare function createVoiceClient(config?: VoiceClientConfig): VoiceClient;