@dotdo/do 0.1.0

package/dist/ai/voice/campaigns.js

@@ -0,0 +1,739 @@
+/**
+ * Outbound Campaign Management
+ *
+ * Manages automated outbound calling campaigns with
+ * scheduling, contact management, and real-time statistics.
+ *
+ * @module ai/voice/campaigns
+ */
+// =============================================================================
+// Campaign Manager
+// =============================================================================
+/**
+ * Outbound campaign manager
+ *
+ * Manages automated outbound calling campaigns with scheduling,
+ * contact list management, retry logic, and statistics.
+ *
+ * @example
+ * ```typescript
+ * const manager = new VoiceCampaignManager(storage, sessionManager, agentManager)
+ *
+ * // Create a campaign
+ * const campaign = await manager.create({
+ *   name: 'Q4 Follow-up',
+ *   agentId: 'vagent_sales',
+ *   contacts: [
+ *     { phone: '+1-555-0001', name: 'Alice' },
+ *     { phone: '+1-555-0002', name: 'Bob' },
+ *   ],
+ *   schedule: {
+ *     startDate: Date.now(),
+ *     callingHours: { start: '09:00', end: '17:00' },
+ *     daysOfWeek: [1, 2, 3, 4, 5],
+ *     timezone: 'America/New_York',
+ *     maxConcurrent: 5,
+ *   },
+ *   settings: {
+ *     maxAttempts: 3,
+ *     retryDelay: 60,
+ *     voicemailDetection: true,
+ *     callerId: '+1-555-0100',
+ *   },
+ * })
+ *
+ * // Start the campaign
+ * await manager.start(campaign.id)
+ *
+ * // Monitor stats
+ * const stats = await manager.getStats(campaign.id)
+ * ```
+ */
+export class VoiceCampaignManager {
+    storage;
+    sessionManager;
+    agentManager;
+    eventHandlers = new Map();
+    /**
+     * Create a campaign manager
+     *
+     * @param storage - DO storage interface
+     * @param sessionManager - Voice session manager
+     * @param agentManager - Voice agent manager
+     */
+    constructor(storage, sessionManager, agentManager) {
+        this.storage = storage;
+        this.sessionManager = sessionManager;
+        this.agentManager = agentManager;
+    }
+    /**
+     * Create a new campaign
+     *
+     * @param options - Campaign options
+     * @returns Created campaign
+     */
+    async create(options) {
+        // Validate agent exists
+        const agent = await this.agentManager.get(options.agentId);
+        if (!agent) {
+            throw new Error(`Voice agent not found: ${options.agentId}`);
+        }
+        const campaignId = `vcamp_${generateId()}`;
+        const now = Date.now();
+        // Process contacts
+        const contacts = options.contacts.map((c, index) => ({
+            id: `contact_${generateId()}`,
+            phone: c.phone,
+            name: c.name,
+            context: c.context,
+            status: 'Pending',
+        }));
+        const campaign = {
+            id: campaignId,
+            name: options.name,
+            agentId: options.agentId,
+            contacts,
+            schedule: options.schedule,
+            status: 'Draft',
+            settings: options.settings,
+            stats: {
+                totalContacts: contacts.length,
+                called: 0,
+                completed: 0,
+                transferred: 0,
+                voicemail: 0,
+                noAnswer: 0,
+                failed: 0,
+                avgDuration: 0,
+                totalCost: 0,
+            },
+            createdAt: now,
+        };
+        await this.storage.put(`voice_campaign:${campaignId}`, campaign);
+        return campaign;
+    }
+    /**
+     * Get a campaign by ID
+     *
+     * @param id - Campaign ID
+     * @returns Campaign or null if not found
+     */
+    async get(id) {
+        const result = await this.storage.get(`voice_campaign:${id}`);
+        return result ?? null;
+    }
+    /**
+     * Update a campaign
+     *
+     * Can only update draft or paused campaigns.
+     *
+     * @param id - Campaign ID
+     * @param options - Fields to update
+     * @returns Updated campaign
+     */
+    async update(id, options) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        if (campaign.status === 'Running' || campaign.status === 'Completed') {
+            throw new Error(`Cannot update campaign in status: ${campaign.status}`);
+        }
+        const updated = {
+            ...campaign,
+            name: options.name ?? campaign.name,
+            schedule: options.schedule ? { ...campaign.schedule, ...options.schedule } : campaign.schedule,
+            settings: options.settings ? { ...campaign.settings, ...options.settings } : campaign.settings,
+        };
+        await this.storage.put(`voice_campaign:${id}`, updated);
+        return updated;
+    }
+    /**
+     * Add contacts to a campaign
+     *
+     * Can only add contacts to draft or paused campaigns.
+     *
+     * @param id - Campaign ID
+     * @param contacts - Contacts to add
+     * @returns Updated campaign
+     */
+    async addContacts(id, contacts) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        if (campaign.status === 'Running' || campaign.status === 'Completed') {
+            throw new Error(`Cannot add contacts to campaign in status: ${campaign.status}`);
+        }
+        const newContacts = contacts.map((c) => ({
+            id: `contact_${generateId()}`,
+            phone: c.phone,
+            name: c.name,
+            context: c.context,
+            status: 'Pending',
+        }));
+        const updated = {
+            ...campaign,
+            contacts: [...campaign.contacts, ...newContacts],
+            stats: campaign.stats ? {
+                ...campaign.stats,
+                totalContacts: campaign.contacts.length + newContacts.length,
+            } : undefined,
+        };
+        await this.storage.put(`voice_campaign:${id}`, updated);
+        return updated;
+    }
+    /**
+     * Remove a contact from a campaign
+     *
+     * @param id - Campaign ID
+     * @param contactId - Contact ID
+     * @returns Updated campaign
+     */
+    async removeContact(id, contactId) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        if (campaign.status === 'Running' || campaign.status === 'Completed') {
+            throw new Error(`Cannot remove contacts from campaign in status: ${campaign.status}`);
+        }
+        const updated = {
+            ...campaign,
+            contacts: campaign.contacts.filter((c) => c.id !== contactId),
+            stats: campaign.stats ? {
+                ...campaign.stats,
+                totalContacts: campaign.contacts.length - 1,
+            } : undefined,
+        };
+        await this.storage.put(`voice_campaign:${id}`, updated);
+        return updated;
+    }
+    /**
+     * Start a campaign
+     *
+     * @param id - Campaign ID
+     * @returns Updated campaign
+     */
+    async start(id) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        if (campaign.status !== 'Draft' && campaign.status !== 'Scheduled' && campaign.status !== 'Paused') {
+            throw new Error(`Cannot start campaign in status: ${campaign.status}`);
+        }
+        const updated = {
+            ...campaign,
+            status: 'Running',
+            startedAt: campaign.startedAt ?? Date.now(),
+        };
+        await this.storage.put(`voice_campaign:${id}`, updated);
+        // Emit started event
+        await this.emit(id, 'started', { campaignId: id });
+        // Schedule first batch of calls
+        await this.scheduleNextBatch(id);
+        return updated;
+    }
+    /**
+     * Pause a running campaign
+     *
+     * @param id - Campaign ID
+     * @returns Updated campaign
+     */
+    async pause(id) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        if (campaign.status !== 'Running') {
+            throw new Error(`Cannot pause campaign in status: ${campaign.status}`);
+        }
+        const updated = {
+            ...campaign,
+            status: 'Paused',
+        };
+        await this.storage.put(`voice_campaign:${id}`, updated);
+        await this.emit(id, 'paused', { campaignId: id });
+        return updated;
+    }
+    /**
+     * Resume a paused campaign
+     *
+     * @param id - Campaign ID
+     * @returns Updated campaign
+     */
+    async resume(id) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        if (campaign.status !== 'Paused') {
+            throw new Error(`Cannot resume campaign in status: ${campaign.status}`);
+        }
+        const updated = {
+            ...campaign,
+            status: 'Running',
+        };
+        await this.storage.put(`voice_campaign:${id}`, updated);
+        await this.emit(id, 'resumed', { campaignId: id });
+        // Resume calling
+        await this.scheduleNextBatch(id);
+        return updated;
+    }
+    /**
+     * Stop a campaign (mark as completed)
+     *
+     * @param id - Campaign ID
+     * @returns Updated campaign
+     */
+    async stop(id) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        const updated = {
+            ...campaign,
+            status: 'Completed',
+            completedAt: Date.now(),
+        };
+        await this.storage.put(`voice_campaign:${id}`, updated);
+        await this.emit(id, 'completed', { campaignId: id });
+        return updated;
+    }
+    /**
+     * Delete a campaign
+     *
+     * @param id - Campaign ID
+     * @returns True if deleted
+     */
+    async delete(id) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            return false;
+        }
+        if (campaign.status === 'Running') {
+            throw new Error('Cannot delete a running campaign');
+        }
+        await this.storage.delete(`voice_campaign:${id}`);
+        return true;
+    }
+    /**
+     * List campaigns
+     *
+     * @param options - Filter and pagination options
+     * @returns List of campaigns
+     */
+    async list(options = {}) {
+        const { status, agentId, limit = 50, offset = 0 } = options;
+        const allCampaigns = await this.storage.list({ prefix: 'voice_campaign:' });
+        let items = [];
+        for (const [, campaign] of allCampaigns) {
+            if (status && campaign.status !== status)
+                continue;
+            if (agentId && campaign.agentId !== agentId)
+                continue;
+            items.push(campaign);
+        }
+        // Sort by createdAt descending
+        items.sort((a, b) => b.createdAt - a.createdAt);
+        const total = items.length;
+        items = items.slice(offset, offset + limit);
+        return {
+            items,
+            total,
+            hasMore: offset + items.length < total,
+        };
+    }
+    /**
+     * Get campaign statistics
+     *
+     * @param id - Campaign ID
+     * @returns Campaign statistics
+     */
+    async getStats(id) {
+        const campaign = await this.get(id);
+        if (!campaign) {
+            throw new Error(`Campaign not found: ${id}`);
+        }
+        // Recalculate stats from contacts
+        const stats = {
+            totalContacts: campaign.contacts.length,
+            called: 0,
+            completed: 0,
+            transferred: 0,
+            voicemail: 0,
+            noAnswer: 0,
+            failed: 0,
+            avgDuration: 0,
+            totalCost: 0,
+        };
+        let totalDuration = 0;
+        let callsWithDuration = 0;
+        for (const contact of campaign.contacts) {
+            if (contact.status === 'Completed' || contact.status === 'Failed') {
+                stats.called++;
+            }
+            if (contact.status === 'Completed') {
+                stats.completed++;
+                // Get session for duration/cost
+                if (contact.sessionId) {
+                    const session = await this.sessionManager.get(contact.sessionId);
+                    if (session) {
+                        if (session.duration) {
+                            totalDuration += session.duration;
+                            callsWithDuration++;
+                        }
+                        if (session.cost) {
+                            stats.totalCost += session.cost.total;
+                        }
+                        if (session.outcome?.type === 'Transferred') {
+                            stats.transferred++;
+                        }
+                        if (session.outcome?.type === 'Voicemail') {
+                            stats.voicemail++;
+                        }
+                        if (session.outcome?.type === 'NoAnswer') {
+                            stats.noAnswer++;
+                        }
+                    }
+                }
+            }
+            if (contact.status === 'Failed') {
+                stats.failed++;
+            }
+        }
+        stats.avgDuration = callsWithDuration > 0 ? totalDuration / callsWithDuration : 0;
+        return stats;
+    }
+    /**
+     * Schedule the next batch of calls
+     *
+     * @param id - Campaign ID
+     */
+    async scheduleNextBatch(id) {
+        const campaign = await this.get(id);
+        if (!campaign || campaign.status !== 'Running') {
+            return;
+        }
+        // Check calling hours
+        if (campaign.schedule && !isWithinCallingHours(campaign.schedule)) {
+            // Schedule alarm for next calling window
+            const nextWindow = getNextCallingWindow(campaign.schedule);
+            // TODO: Set DO alarm
+            // await this.ctx.storage.setAlarm(nextWindow)
+            return;
+        }
+        // Get pending contacts up to maxConcurrent
+        const maxConcurrent = campaign.schedule?.maxConcurrent ?? 1;
+        const pendingContacts = campaign.contacts
+            .filter((c) => c.status === 'Pending')
+            .slice(0, maxConcurrent);
+        if (pendingContacts.length === 0) {
+            // No more contacts, mark as completed
+            await this.stop(id);
+            return;
+        }
+        // Start calls for each contact
+        for (const contact of pendingContacts) {
+            await this.startContactCall(id, contact);
+        }
+    }
+    /**
+     * Start a call for a campaign contact
+     *
+     * @param campaignId - Campaign ID
+     * @param contact - Contact to call
+     */
+    async startContactCall(campaignId, contact) {
+        const campaign = await this.get(campaignId);
+        if (!campaign)
+            return;
+        try {
+            // Update contact status
+            await this.updateContactStatus(campaignId, contact.id, 'Calling');
+            // Start the call
+            const session = await this.sessionManager.startOutbound({
+                agentId: campaign.agentId,
+                phone: contact.phone,
+                context: {
+                    campaignId,
+                    contactId: contact.id,
+                    contactName: contact.name,
+                    ...contact.context,
+                },
+                metadata: {
+                    campaignId,
+                    contactId: contact.id,
+                },
+            });
+            // Update contact with session ID
+            await this.updateContactSession(campaignId, contact.id, session.id);
+            await this.emit(campaignId, 'contact_called', {
+                campaignId,
+                contactId: contact.id,
+                sessionId: session.id,
+            });
+        }
+        catch (error) {
+            // Mark contact as failed
+            await this.updateContactStatus(campaignId, contact.id, 'Failed');
+            await this.emit(campaignId, 'contact_failed', {
+                campaignId,
+                contactId: contact.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Update contact status
+     */
+    async updateContactStatus(campaignId, contactId, status) {
+        const campaign = await this.get(campaignId);
+        if (!campaign)
+            return;
+        const updated = {
+            ...campaign,
+            contacts: campaign.contacts.map((c) => c.id === contactId ? { ...c, status } : c),
+        };
+        await this.storage.put(`voice_campaign:${campaignId}`, updated);
+    }
+    /**
+     * Update contact with session ID
+     */
+    async updateContactSession(campaignId, contactId, sessionId) {
+        const campaign = await this.get(campaignId);
+        if (!campaign)
+            return;
+        const updated = {
+            ...campaign,
+            contacts: campaign.contacts.map((c) => c.id === contactId ? { ...c, sessionId } : c),
+        };
+        await this.storage.put(`voice_campaign:${campaignId}`, updated);
+    }
+    /**
+     * Handle session completion (called from webhook processor)
+     *
+     * @param campaignId - Campaign ID
+     * @param contactId - Contact ID
+     * @param outcome - Call outcome
+     */
+    async handleSessionComplete(campaignId, contactId, outcome) {
+        await this.updateContactStatus(campaignId, contactId, outcome);
+        await this.emit(campaignId, outcome === 'Completed' ? 'contact_completed' : 'contact_failed', {
+            campaignId,
+            contactId,
+        });
+        // Update stats
+        await this.emit(campaignId, 'stats_updated', await this.getStats(campaignId));
+        // Schedule next batch
+        await this.scheduleNextBatch(campaignId);
+    }
+    /**
+     * Subscribe to campaign events
+     *
+     * @param campaignId - Campaign ID
+     * @param event - Event type
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    on(campaignId, event, handler) {
+        const key = `${campaignId}:${event}`;
+        if (!this.eventHandlers.has(key)) {
+            this.eventHandlers.set(key, new Set());
+        }
+        this.eventHandlers.get(key).add(handler);
+        return () => {
+            this.eventHandlers.get(key)?.delete(handler);
+        };
+    }
+    /**
+     * Watch campaign stats (returns async iterator)
+     *
+     * @param campaignId - Campaign ID
+     * @returns Async iterator of stats updates
+     */
+    async *watchStats(campaignId) {
+        // Initial stats
+        yield await this.getStats(campaignId);
+        // Create a channel for stats updates
+        const queue = [];
+        let resolve = null;
+        const unsubscribe = this.on(campaignId, 'stats_updated', (stats) => {
+            queue.push(stats);
+            if (resolve) {
+                resolve();
+                resolve = null;
+            }
+        });
+        try {
+            while (true) {
+                if (queue.length > 0) {
+                    yield queue.shift();
+                }
+                else {
+                    // Wait for next update
+                    await new Promise((r) => { resolve = r; });
+                }
+                // Check if campaign is still running
+                const campaign = await this.get(campaignId);
+                if (!campaign || campaign.status === 'Completed') {
+                    break;
+                }
+            }
+        }
+        finally {
+            unsubscribe();
+        }
+    }
+    /**
+     * Emit a campaign event
+     */
+    async emit(campaignId, event, data) {
+        const key = `${campaignId}:${event}`;
+        const handlers = this.eventHandlers.get(key);
+        if (handlers) {
+            for (const handler of handlers) {
+                await handler(data);
+            }
+        }
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Generate a random ID
+ */
+function generateId() {
+    // TODO: Use nanoid
+    return Math.random().toString(36).substring(2, 15);
+}
+/**
+ * Check if current time is within calling hours
+ */
+function isWithinCallingHours(schedule) {
+    const now = new Date();
+    // Check day of week
+    const dayOfWeek = now.getDay();
+    if (!schedule.daysOfWeek.includes(dayOfWeek)) {
+        return false;
+    }
+    // Parse calling hours
+    const [startHour, startMin] = schedule.callingHours.start.split(':').map(Number);
+    const [endHour, endMin] = schedule.callingHours.end.split(':').map(Number);
+    // Get current time in campaign timezone (simplified - should use proper timezone lib)
+    const currentHour = now.getHours();
+    const currentMin = now.getMinutes();
+    const currentMinutes = currentHour * 60 + currentMin;
+    const startMinutes = startHour * 60 + startMin;
+    const endMinutes = endHour * 60 + endMin;
+    return currentMinutes >= startMinutes && currentMinutes < endMinutes;
+}
+/**
+ * Get next calling window start time
+ */
+function getNextCallingWindow(schedule) {
+    const now = new Date();
+    // Find next valid day
+    for (let i = 0; i < 7; i++) {
+        const checkDate = new Date(now.getTime() + i * 24 * 60 * 60 * 1000);
+        const dayOfWeek = checkDate.getDay();
+        if (schedule.daysOfWeek.includes(dayOfWeek)) {
+            // Set to start of calling hours
+            const [startHour, startMin] = schedule.callingHours.start.split(':').map(Number);
+            checkDate.setHours(startHour, startMin, 0, 0);
+            // If today and past calling hours, skip to next valid day
+            if (i === 0 && checkDate.getTime() < now.getTime()) {
+                continue;
+            }
+            return checkDate.getTime();
+        }
+    }
+    // Fallback to tomorrow
+    return now.getTime() + 24 * 60 * 60 * 1000;
+}
+// =============================================================================
+// Singleton Access
+// =============================================================================
+let defaultManager = null;
+/**
+ * Voice campaigns singleton access
+ */
+export const VoiceCampaigns = {
+    /**
+     * Initialize with dependencies
+     */
+    init(storage, sessionManager, agentManager) {
+        defaultManager = new VoiceCampaignManager(storage, sessionManager, agentManager);
+    },
+    /**
+     * Create a campaign
+     */
+    async create(options) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.create(options);
+    },
+    /**
+     * Get a campaign
+     */
+    async get(id) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.get(id);
+    },
+    /**
+     * Start a campaign
+     */
+    async start(id) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.start(id);
+    },
+    /**
+     * Pause a campaign
+     */
+    async pause(id) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.pause(id);
+    },
+    /**
+     * Resume a campaign
+     */
+    async resume(id) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.resume(id);
+    },
+    /**
+     * Get campaign stats
+     */
+    async getStats(id) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.getStats(id);
+    },
+    /**
+     * List campaigns
+     */
+    async list(options) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.list(options);
+    },
+    /**
+     * Watch campaign stats
+     */
+    watchStats(id) {
+        if (!defaultManager)
+            throw new Error('VoiceCampaigns not initialized');
+        return defaultManager.watchStats(id);
+    },
+};
+// =============================================================================
+// Type Exports
+// =============================================================================
+// Note: DurableObjectStorage is a Cloudflare Workers type, imported at runtime
+//# sourceMappingURL=campaigns.js.map