@auxiora/channels 1.0.0

package/src/adapters/whatsapp.ts

@@ -0,0 +1,342 @@
+import { audit } from '@auxiora/audit';
+import type {
+  ChannelAdapter,
+  InboundMessage,
+  OutboundMessage,
+  SendResult,
+} from '../types.js';
+
+export interface WhatsAppAdapterConfig {
+  phoneNumberId: string;
+  accessToken: string;
+  verifyToken: string;
+  allowedNumbers?: string[];
+}
+
+interface WhatsAppWebhookBody {
+  object: string;
+  entry: Array<{
+    id: string;
+    changes: Array<{
+      value: {
+        messaging_product: string;
+        metadata: {
+          display_phone_number: string;
+          phone_number_id: string;
+        };
+        contacts?: Array<{
+          profile: { name: string };
+          wa_id: string;
+        }>;
+        messages?: Array<WhatsAppIncomingMessage>;
+        statuses?: Array<{
+          id: string;
+          status: string;
+          timestamp: string;
+        }>;
+      };
+      field: string;
+    }>;
+  }>;
+}
+
+interface WhatsAppIncomingMessage {
+  from: string;
+  id: string;
+  timestamp: string;
+  type: string;
+  text?: { body: string };
+  image?: {
+    id: string;
+    mime_type: string;
+    sha256: string;
+    caption?: string;
+  };
+  document?: {
+    id: string;
+    mime_type: string;
+    filename?: string;
+    sha256: string;
+    caption?: string;
+  };
+  audio?: {
+    id: string;
+    mime_type: string;
+  };
+  video?: {
+    id: string;
+    mime_type: string;
+  };
+  context?: {
+    from: string;
+    id: string;
+  };
+}
+
+interface WhatsAppSendResponse {
+  messaging_product: string;
+  contacts: Array<{ wa_id: string }>;
+  messages: Array<{ id: string }>;
+}
+
+const GRAPH_API_BASE = 'https://graph.facebook.com/v18.0';
+const MAX_MESSAGE_LENGTH = 4096;
+
+export class WhatsAppAdapter implements ChannelAdapter {
+  readonly type = 'whatsapp' as const;
+  readonly name = 'WhatsApp';
+
+  private config: WhatsAppAdapterConfig;
+  private messageHandler?: (message: InboundMessage) => Promise<void>;
+  private errorHandler?: (error: Error) => void;
+  private connected = false;
+
+  constructor(config: WhatsAppAdapterConfig) {
+    this.config = config;
+  }
+
+  async connect(): Promise<void> {
+    // Verify credentials by checking the phone number ID
+    const response = await fetch(
+      `${GRAPH_API_BASE}/${this.config.phoneNumberId}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${this.config.accessToken}`,
+        },
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error(`Failed to verify WhatsApp credentials: ${response.status} ${response.statusText}`);
+    }
+
+    this.connected = true;
+
+    audit('channel.connected', {
+      channelType: 'whatsapp',
+      phoneNumberId: this.config.phoneNumberId,
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    audit('channel.disconnected', { channelType: 'whatsapp' });
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /**
+   * Verify webhook subscription from Meta.
+   * Returns the challenge string if the verify token matches.
+   */
+  verifyWebhook(mode: string, token: string, challenge: string): string | null {
+    if (mode === 'subscribe' && token === this.config.verifyToken) {
+      return challenge;
+    }
+    return null;
+  }
+
+  /**
+   * Handle incoming webhook from WhatsApp Business API.
+   * Call this from your HTTP server when receiving POST to your webhook URL.
+   */
+  async handleWebhook(body: WhatsAppWebhookBody): Promise<void> {
+    if (body.object !== 'whatsapp_business_account') return;
+
+    for (const entry of body.entry) {
+      for (const change of entry.changes) {
+        if (change.field !== 'messages') continue;
+
+        const messages = change.value.messages;
+        if (!messages) continue;
+
+        const contacts = change.value.contacts;
+
+        for (const msg of messages) {
+          const contact = contacts?.find((c) => c.wa_id === msg.from);
+          await this.handleMessage(msg, contact);
+        }
+      }
+    }
+  }
+
+  private async handleMessage(
+    msg: WhatsAppIncomingMessage,
+    contact?: { profile: { name: string }; wa_id: string },
+  ): Promise<void> {
+    // Only process text messages for now
+    if (msg.type !== 'text' && msg.type !== 'image' && msg.type !== 'document') return;
+
+    // Check allowed numbers
+    if (this.config.allowedNumbers?.length && !this.config.allowedNumbers.includes(msg.from)) {
+      audit('message.filtered', { channelType: 'whatsapp', senderId: msg.from, reason: 'number_not_allowed' });
+      return;
+    }
+
+    const inbound = this.toInboundMessage(msg, contact);
+
+    audit('message.received', {
+      channelType: 'whatsapp',
+      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)));
+      }
+    }
+  }
+
+  private toInboundMessage(
+    msg: WhatsAppIncomingMessage,
+    contact?: { profile: { name: string }; wa_id: string },
+  ): InboundMessage {
+    let content = '';
+    const attachments: InboundMessage['attachments'] = [];
+
+    switch (msg.type) {
+      case 'text':
+        content = msg.text?.body || '';
+        break;
+      case 'image':
+        content = msg.image?.caption || '';
+        attachments.push({
+          type: 'image',
+          mimeType: msg.image?.mime_type,
+        });
+        break;
+      case 'document':
+        content = msg.document?.caption || '';
+        attachments.push({
+          type: 'file',
+          mimeType: msg.document?.mime_type,
+          filename: msg.document?.filename,
+        });
+        break;
+      case 'audio':
+        attachments.push({
+          type: 'audio',
+          mimeType: msg.audio?.mime_type,
+        });
+        break;
+      case 'video':
+        attachments.push({
+          type: 'video',
+          mimeType: msg.video?.mime_type,
+        });
+        break;
+    }
+
+    return {
+      id: msg.id,
+      channelType: 'whatsapp',
+      channelId: msg.from,
+      senderId: msg.from,
+      senderName: contact?.profile.name,
+      content,
+      timestamp: parseInt(msg.timestamp, 10) * 1000,
+      replyToId: msg.context?.id,
+      attachments: attachments.length > 0 ? attachments : undefined,
+      raw: msg,
+    };
+  }
+
+  async send(channelId: string, message: OutboundMessage): Promise<SendResult> {
+    try {
+      const chunks = this.chunkMessage(message.content);
+      let lastMessageId: string | undefined;
+
+      for (const chunk of chunks) {
+        const body: Record<string, unknown> = {
+          messaging_product: 'whatsapp',
+          recipient_type: 'individual',
+          to: channelId,
+          type: 'text',
+          text: { body: chunk },
+        };
+
+        if (message.replyToId) {
+          body.context = { message_id: message.replyToId };
+        }
+
+        const response = await fetch(
+          `${GRAPH_API_BASE}/${this.config.phoneNumberId}/messages`,
+          {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${this.config.accessToken}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+          },
+        );
+
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => response.statusText);
+          throw new Error(`WhatsApp API error ${response.status}: ${errorText}`);
+        }
+
+        const result = await response.json() as WhatsAppSendResponse;
+        lastMessageId = result.messages?.[0]?.id;
+      }
+
+      audit('message.sent', {
+        channelType: 'whatsapp',
+        channelId,
+        messageId: lastMessageId,
+      });
+
+      return { success: true, messageId: lastMessageId };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      audit('channel.error', {
+        channelType: 'whatsapp',
+        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;
+  }
+
+  onMessage(handler: (message: InboundMessage) => Promise<void>): void {
+    this.messageHandler = handler;
+  }
+
+  onError(handler: (error: Error) => void): void {
+    this.errorHandler = handler;
+  }
+}

package/src/adapters/zalo.ts

@@ -0,0 +1,319 @@
+import { createHmac } from 'node:crypto';
+import { audit } from '@auxiora/audit';
+import type {
+  ChannelAdapter,
+  InboundMessage,
+  OutboundMessage,
+  SendResult,
+} from '../types.js';
+
+export interface ZaloAdapterConfig {
+  oaAccessToken: string;
+  oaSecretKey: string;
+  allowedUserIds?: string[];
+}
+
+interface ZaloWebhookEvent {
+  app_id: string;
+  sender: {
+    id: string;
+  };
+  recipient: {
+    id: string;
+  };
+  event_name: string;
+  message?: {
+    msg_id: string;
+    text?: string;
+    attachments?: Array<{
+      type: string;
+      payload: {
+        url?: string;
+        thumbnail?: string;
+        id?: string;
+        size?: number;
+        name?: string;
+        type?: string;
+      };
+    }>;
+    quote_msg_id?: string;
+  };
+  timestamp: string;
+}
+
+interface ZaloSendResponse {
+  error: number;
+  message: string;
+  data?: {
+    message_id: string;
+  };
+}
+
+interface ZaloUserProfileResponse {
+  error: number;
+  message: string;
+  data?: {
+    display_name: string;
+    user_id: string;
+    avatar?: string;
+  };
+}
+
+const ZALO_OA_API_BASE = 'https://openapi.zalo.me/v3.0/oa';
+const MAX_MESSAGE_LENGTH = 2000;
+
+export class ZaloAdapter implements ChannelAdapter {
+  readonly type = 'zalo' as const;
+  readonly name = 'Zalo';
+
+  private config: ZaloAdapterConfig;
+  private messageHandler?: (message: InboundMessage) => Promise<void>;
+  private errorHandler?: (error: Error) => void;
+  private connected = false;
+  private userNameCache: Map<string, string> = new Map();
+
+  constructor(config: ZaloAdapterConfig) {
+    this.config = config;
+  }
+
+  async connect(): Promise<void> {
+    // Verify credentials by fetching OA info
+    const response = await fetch(`${ZALO_OA_API_BASE}/getoa`, {
+      headers: {
+        access_token: this.config.oaAccessToken,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to verify Zalo credentials: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const result = (await response.json()) as { error: number; message: string };
+    if (result.error !== 0) {
+      throw new Error(`Zalo API error: ${result.message}`);
+    }
+
+    this.connected = true;
+
+    audit('channel.connected', { channelType: 'zalo' });
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    this.userNameCache.clear();
+    audit('channel.disconnected', { channelType: 'zalo' });
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /**
+   * Verify the webhook signature from Zalo.
+   * Returns true if the signature is valid.
+   */
+  verifyWebhookSignature(body: string, signature: string): boolean {
+    const hmac = createHmac('sha256', this.config.oaSecretKey);
+    hmac.update(body);
+    const expected = hmac.digest('hex');
+    return expected === signature;
+  }
+
+  /**
+   * Handle incoming webhook from Zalo OA.
+   * Call this from your HTTP server when receiving POST to your webhook URL.
+   */
+  async handleWebhook(event: ZaloWebhookEvent): Promise<void> {
+    if (event.event_name !== 'user_send_text' && event.event_name !== 'user_send_image') {
+      return;
+    }
+
+    if (!event.message) return;
+
+    // Check allowed users
+    const senderId = event.sender.id;
+    if (
+      this.config.allowedUserIds?.length &&
+      !this.config.allowedUserIds.includes(senderId)
+    ) {
+      audit('message.filtered', {
+        channelType: 'zalo',
+        senderId,
+        reason: 'user_not_allowed',
+      });
+      return;
+    }
+
+    const senderName = await this.getUserName(senderId);
+    const inbound = this.toInboundMessage(event, senderName);
+
+    audit('message.received', {
+      channelType: 'zalo',
+      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)));
+      }
+    }
+  }
+
+  private async getUserName(userId: string): Promise<string | undefined> {
+    const cached = this.userNameCache.get(userId);
+    if (cached) return cached;
+
+    try {
+      const response = await fetch(
+        `${ZALO_OA_API_BASE}/getprofile?data=${encodeURIComponent(JSON.stringify({ user_id: userId }))}`,
+        {
+          headers: {
+            access_token: this.config.oaAccessToken,
+          },
+        },
+      );
+
+      if (response.ok) {
+        const result = (await response.json()) as ZaloUserProfileResponse;
+        if (result.data?.display_name) {
+          this.userNameCache.set(userId, result.data.display_name);
+          return result.data.display_name;
+        }
+      }
+    } catch {
+      // Silently fail - name is optional
+    }
+
+    return undefined;
+  }
+
+  private toInboundMessage(
+    event: ZaloWebhookEvent,
+    senderName?: string,
+  ): InboundMessage {
+    const message = event.message!;
+    const content = message.text || '';
+
+    return {
+      id: message.msg_id,
+      channelType: 'zalo',
+      channelId: event.sender.id,
+      senderId: event.sender.id,
+      senderName,
+      content,
+      timestamp: parseInt(event.timestamp, 10),
+      replyToId: message.quote_msg_id,
+      attachments: message.attachments?.map((a) => ({
+        type: a.type === 'image'
+          ? ('image' as const)
+          : a.type === 'audio'
+            ? ('audio' as const)
+            : a.type === 'video'
+              ? ('video' as const)
+              : ('file' as const),
+        url: a.payload.url || a.payload.thumbnail,
+        mimeType: a.payload.type,
+        filename: a.payload.name,
+        size: a.payload.size,
+      })),
+      raw: event,
+    };
+  }
+
+  async send(channelId: string, message: OutboundMessage): Promise<SendResult> {
+    try {
+      const chunks = this.chunkMessage(message.content);
+      let lastMessageId: string | undefined;
+
+      for (const chunk of chunks) {
+        const body: Record<string, unknown> = {
+          recipient: { user_id: channelId },
+          message: { text: chunk },
+        };
+
+        if (message.replyToId) {
+          body.quote_message_id = message.replyToId;
+        }
+
+        const response = await fetch(`${ZALO_OA_API_BASE}/message/cs`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            access_token: this.config.oaAccessToken,
+          },
+          body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => response.statusText);
+          throw new Error(`Zalo API error ${response.status}: ${errorText}`);
+        }
+
+        const result = (await response.json()) as ZaloSendResponse;
+        if (result.error !== 0) {
+          throw new Error(`Zalo send error: ${result.message}`);
+        }
+
+        lastMessageId = result.data?.message_id;
+      }
+
+      audit('message.sent', {
+        channelType: 'zalo',
+        channelId,
+        messageId: lastMessageId,
+      });
+
+      return { success: true, messageId: lastMessageId };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      audit('channel.error', {
+        channelType: 'zalo',
+        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;
+  }
+
+  onMessage(handler: (message: InboundMessage) => Promise<void>): void {
+    this.messageHandler = handler;
+  }
+
+  onError(handler: (error: Error) => void): void {
+    this.errorHandler = handler;
+  }
+}