@auxiora/channels 1.0.0

package/src/adapters/telegram.ts

@@ -0,0 +1,208 @@
+import { Bot, Context } from 'grammy';
+import { audit } from '@auxiora/audit';
+import type {
+  ChannelAdapter,
+  InboundMessage,
+  OutboundMessage,
+  SendResult,
+} from '../types.js';
+
+export interface TelegramAdapterConfig {
+  token: string;
+  webhookUrl?: string;
+  allowedChats?: string[];
+}
+
+const MAX_MESSAGE_LENGTH = 4096;
+
+export class TelegramAdapter implements ChannelAdapter {
+  readonly type = 'telegram' as const;
+  readonly name = 'Telegram';
+
+  private bot: Bot;
+  private config: TelegramAdapterConfig;
+  private messageHandler?: (message: InboundMessage) => Promise<void>;
+  private errorHandler?: (error: Error) => void;
+  private connected = false;
+
+  constructor(config: TelegramAdapterConfig) {
+    this.config = config;
+    this.bot = new Bot(config.token);
+    this.setupEventHandlers();
+  }
+
+  private setupEventHandlers(): void {
+    this.bot.on('message:text', async (ctx: Context) => {
+      const message = ctx.message;
+      if (!message || !message.text) return;
+
+      // Check chat allowlist
+      if (
+        this.config.allowedChats?.length &&
+        !this.config.allowedChats.includes(String(message.chat.id))
+      ) {
+        return;
+      }
+
+      const inbound = this.toInboundMessage(ctx);
+
+      audit('message.received', {
+        channelType: 'telegram',
+        senderId: inbound.senderId,
+        channelId: inbound.channelId,
+      });
+
+      if (this.messageHandler) {
+        try {
+          await this.messageHandler(inbound);
+        } catch (error) {
+          this.errorHandler?.(error instanceof Error ? error : new Error(String(error)));
+        }
+      }
+    });
+
+    this.bot.catch((error) => {
+      audit('channel.error', { channelType: 'telegram', error: error.message });
+      this.errorHandler?.(error);
+    });
+  }
+
+  private toInboundMessage(ctx: Context): InboundMessage {
+    const message = ctx.message!;
+    const from = message.from!;
+
+    return {
+      id: String(message.message_id),
+      channelType: 'telegram',
+      channelId: String(message.chat.id),
+      senderId: String(from.id),
+      senderName: from.first_name + (from.last_name ? ` ${from.last_name}` : ''),
+      content: message.text || '',
+      timestamp: message.date * 1000,
+      replyToId: message.reply_to_message
+        ? String(message.reply_to_message.message_id)
+        : undefined,
+      raw: message,
+    };
+  }
+
+  async connect(): Promise<void> {
+    if (this.config.webhookUrl) {
+      await this.bot.api.setWebhook(this.config.webhookUrl);
+    } else {
+      // Start polling
+      this.bot.start({
+        onStart: () => {
+          audit('channel.connected', { channelType: 'telegram' });
+          this.connected = true;
+        },
+      });
+    }
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    await this.bot.stop();
+    this.connected = false;
+    audit('channel.disconnected', { channelType: 'telegram' });
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  async send(channelId: string, message: OutboundMessage): Promise<SendResult> {
+    try {
+      const chatId = parseInt(channelId, 10);
+
+      // Chunk long messages
+      const chunks = this.chunkMessage(message.content);
+      let lastMessageId: number | undefined;
+
+      for (const chunk of chunks) {
+        const sent = await this.bot.api.sendMessage(chatId, chunk, {
+          parse_mode: message.formatting?.markdown ? 'MarkdownV2' : undefined,
+          reply_parameters: message.replyToId
+            ? { message_id: parseInt(message.replyToId, 10) }
+            : undefined,
+        });
+        lastMessageId = sent.message_id;
+      }
+
+      audit('message.sent', {
+        channelType: 'telegram',
+        channelId,
+        messageId: lastMessageId,
+      });
+
+      return { success: true, messageId: String(lastMessageId) };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      audit('channel.error', {
+        channelType: 'telegram',
+        action: 'send',
+        error: errorMessage,
+      });
+      return { success: false, error: errorMessage };
+    }
+  }
+
+  private chunkMessage(content: string): string[] {
+    if (content.length <= MAX_MESSAGE_LENGTH) {
+      return [content];
+    }
+
+    const chunks: string[] = [];
+    let remaining = content;
+
+    while (remaining.length > 0) {
+      if (remaining.length <= MAX_MESSAGE_LENGTH) {
+        chunks.push(remaining);
+        break;
+      }
+
+      let breakPoint = remaining.lastIndexOf('\n', MAX_MESSAGE_LENGTH);
+      if (breakPoint === -1 || breakPoint < MAX_MESSAGE_LENGTH / 2) {
+        breakPoint = remaining.lastIndexOf(' ', MAX_MESSAGE_LENGTH);
+      }
+      if (breakPoint === -1 || breakPoint < MAX_MESSAGE_LENGTH / 2) {
+        breakPoint = MAX_MESSAGE_LENGTH;
+      }
+
+      chunks.push(remaining.slice(0, breakPoint));
+      remaining = remaining.slice(breakPoint).trimStart();
+    }
+
+    return chunks;
+  }
+
+  async startTyping(channelId: string): Promise<() => void> {
+    const chatId = parseInt(channelId, 10);
+    // Send immediately, then repeat every 4s (Telegram typing expires after ~5s)
+    let stopped = false;
+    this.bot.api.sendChatAction(chatId, 'typing').catch((e: Error) => {
+      audit('channel.error', { channelType: 'telegram', action: 'typing', error: e.message });
+    });
+    const interval = setInterval(() => {
+      if (stopped) return;
+      this.bot.api.sendChatAction(chatId, 'typing').catch(() => {});
+    }, 4000);
+    return () => {
+      stopped = true;
+      clearInterval(interval);
+    };
+  }
+
+  // Webhook handler for serverless deployments
+  async handleWebhook(body: unknown): Promise<void> {
+    await this.bot.handleUpdate(body as Parameters<typeof this.bot.handleUpdate>[0]);
+  }
+
+  onMessage(handler: (message: InboundMessage) => Promise<void>): void {
+    this.messageHandler = handler;
+  }
+
+  onError(handler: (error: Error) => void): void {
+    this.errorHandler = handler;
+  }
+}

package/src/adapters/twilio.ts

@@ -0,0 +1,256 @@
+import Twilio from 'twilio';
+import { audit } from '@auxiora/audit';
+import type {
+  ChannelAdapter,
+  InboundMessage,
+  OutboundMessage,
+  SendResult,
+} from '../types.js';
+
+export interface TwilioAdapterConfig {
+  accountSid: string;
+  authToken: string;
+  phoneNumber: string;          // Your Twilio phone number for SMS
+  whatsappNumber?: string;      // WhatsApp-enabled number (format: whatsapp:+1234567890)
+  webhookUrl?: string;          // For incoming messages
+  allowedNumbers?: string[];
+}
+
+export interface TwilioWebhookBody {
+  MessageSid: string;
+  AccountSid: string;
+  From: string;
+  To: string;
+  Body: string;
+  NumMedia?: string;
+  MediaUrl0?: string;
+  MediaContentType0?: string;
+}
+
+const MAX_SMS_LENGTH = 1600;     // SMS segment limit
+const MAX_WHATSAPP_LENGTH = 4096;
+
+export class TwilioAdapter implements ChannelAdapter {
+  readonly type = 'twilio' as const;
+  readonly name = 'Twilio';
+
+  private client: Twilio.Twilio;
+  private config: TwilioAdapterConfig;
+  private messageHandler?: (message: InboundMessage) => Promise<void>;
+  private errorHandler?: (error: Error) => void;
+  private connected = false;
+
+  constructor(config: TwilioAdapterConfig) {
+    this.config = config;
+    this.client = Twilio(config.accountSid, config.authToken);
+  }
+
+  async connect(): Promise<void> {
+    // Verify credentials by fetching account info
+    try {
+      await this.client.api.accounts(this.config.accountSid).fetch();
+      this.connected = true;
+      audit('channel.connected', { channelType: 'twilio' });
+    } catch (error) {
+      throw new Error(`Failed to connect to Twilio: ${error instanceof Error ? error.message : error}`);
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    audit('channel.disconnected', { channelType: 'twilio' });
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /**
+   * Handle incoming webhook from Twilio
+   * Call this from your HTTP server when receiving POST to your webhook URL
+   */
+  async handleWebhook(body: TwilioWebhookBody): Promise<string | null> {
+    const isWhatsApp = body.From.startsWith('whatsapp:');
+
+    // Check allowed numbers (strip whatsapp: prefix for matching)
+    const senderNumber = isWhatsApp ? body.From.replace('whatsapp:', '') : body.From;
+    if (this.config.allowedNumbers?.length && !this.config.allowedNumbers.includes(senderNumber)) {
+      audit('message.filtered', { channelType: 'twilio', senderId: body.From, reason: 'number_not_allowed' });
+      return null;
+    }
+
+    const inbound: InboundMessage = {
+      id: body.MessageSid,
+      channelType: 'twilio',
+      channelId: isWhatsApp ? 'whatsapp' : 'sms',
+      senderId: body.From,
+      content: body.Body,
+      timestamp: Date.now(),
+      attachments: body.NumMedia && parseInt(body.NumMedia, 10) > 0
+        ? [{
+            type: body.MediaContentType0?.startsWith('image/') ? 'image' : 'file',
+            url: body.MediaUrl0,
+            mimeType: body.MediaContentType0,
+          }]
+        : undefined,
+      raw: body,
+    };
+
+    audit('message.received', {
+      channelType: 'twilio',
+      senderId: inbound.senderId,
+      channelId: inbound.channelId,
+      isWhatsApp,
+    });
+
+    if (this.messageHandler) {
+      try {
+        await this.messageHandler(inbound);
+      } catch (error) {
+        this.errorHandler?.(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+
+    // Return null to indicate no TwiML response needed
+    // Or return TwiML XML string if you want to respond immediately
+    return null;
+  }
+
+  /**
+   * Send message to a phone number
+   * @param channelId Phone number in E.164 format (+1234567890) or whatsapp:+1234567890
+   */
+  async send(channelId: string, message: OutboundMessage): Promise<SendResult> {
+    try {
+      const isWhatsApp = channelId.startsWith('whatsapp:');
+      const fromNumber = isWhatsApp
+        ? this.config.whatsappNumber || `whatsapp:${this.config.phoneNumber}`
+        : this.config.phoneNumber;
+
+      if (!fromNumber) {
+        return { success: false, error: 'No phone number configured for this channel type' };
+      }
+
+      const maxLength = isWhatsApp ? MAX_WHATSAPP_LENGTH : MAX_SMS_LENGTH;
+      const chunks = this.chunkMessage(message.content, maxLength);
+      let lastMessageSid: string | undefined;
+
+      for (const chunk of chunks) {
+        const sent = await this.client.messages.create({
+          from: fromNumber,
+          to: channelId,
+          body: chunk,
+        });
+        lastMessageSid = sent.sid;
+      }
+
+      audit('message.sent', {
+        channelType: 'twilio',
+        channelId,
+        messageId: lastMessageSid,
+        isWhatsApp,
+      });
+
+      return { success: true, messageId: lastMessageSid };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      audit('channel.error', {
+        channelType: 'twilio',
+        action: 'send',
+        error: errorMessage,
+      });
+      return { success: false, error: errorMessage };
+    }
+  }
+
+  /**
+   * Send SMS to a phone number
+   */
+  async sendSMS(to: string, message: string): Promise<SendResult> {
+    // Ensure proper format
+    const phoneNumber = to.startsWith('+') ? to : `+${to}`;
+    return this.send(phoneNumber, { content: message });
+  }
+
+  /**
+   * Send WhatsApp message
+   */
+  async sendWhatsApp(to: string, message: string): Promise<SendResult> {
+    // Ensure proper format
+    const phoneNumber = to.replace('whatsapp:', '');
+    const whatsappTo = `whatsapp:${phoneNumber.startsWith('+') ? phoneNumber : `+${phoneNumber}`}`;
+    return this.send(whatsappTo, { content: message });
+  }
+
+  private chunkMessage(content: string, maxLength: number): string[] {
+    if (content.length <= maxLength) {
+      return [content];
+    }
+
+    const chunks: string[] = [];
+    let remaining = content;
+
+    while (remaining.length > 0) {
+      if (remaining.length <= maxLength) {
+        chunks.push(remaining);
+        break;
+      }
+
+      let breakPoint = remaining.lastIndexOf('\n', maxLength);
+      if (breakPoint === -1 || breakPoint < maxLength / 2) {
+        breakPoint = remaining.lastIndexOf(' ', maxLength);
+      }
+      if (breakPoint === -1 || breakPoint < maxLength / 2) {
+        breakPoint = maxLength;
+      }
+
+      chunks.push(remaining.slice(0, breakPoint));
+      remaining = remaining.slice(breakPoint).trimStart();
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Validate Twilio webhook signature
+   */
+  validateWebhookSignature(
+    signature: string,
+    url: string,
+    params: Record<string, string>
+  ): boolean {
+    return Twilio.validateRequest(
+      this.config.authToken,
+      signature,
+      url,
+      params
+    );
+  }
+
+  /**
+   * Generate TwiML response for immediate reply
+   */
+  static generateTwiML(message: string): string {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Message>${this.escapeXml(message)}</Message>
+</Response>`;
+  }
+
+  private static escapeXml(text: string): string {
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  onMessage(handler: (message: InboundMessage) => Promise<void>): void {
+    this.messageHandler = handler;
+  }
+
+  onError(handler: (error: Error) => void): void {
+    this.errorHandler = handler;
+  }
+}