feat: add 'raw' event support for debugging raw events from LightSpeed and whatsmeow

Author: aiko-chan-ai

DOCS.md

@@ -78,6 +78,7 @@
   * [`disconnected`](#event-disconnected) 🔵🟢
   * [`error`](#event-error) 🔵🟢
   * [`deviceDataChanged`](#event-deviceDataChanged) 🟢
+  * [`raw`](#event-raw) 🔵🟢
 * [Types](#types)
 
 ---
@@ -1370,6 +1371,7 @@ if (attachment.stickerId === THUMBS_UP_STICKER_IDS.LARGE) {
 | `e2eeReceipt` | ❌ | 🟢 | Message read (E2EE) |
 | `e2eeConnected` | ❌ | 🟢 | E2EE connection successful |
 | `deviceDataChanged` | ❌ | 🟢 | Device data changed |
+| `raw` | 🔵 | 🟢 | Raw event from LightSpeed/whatsmeow |
 | `fullyReady` | 🔵 | 🟢 | Client fully ready |
 | `disconnected` | 🔵 | 🟢 | Disconnected |
 | `error` | 🔵 | 🟢 | Error occurred |
@@ -1720,6 +1722,39 @@ This event is only emitted when you initialize the client with the `deviceData`
 
 ---
 
+<a name="event-raw"></a>
+## Event: 'raw'
+
+> 🔵🟢 **Both Socket and E2EE** - All raw events from LightSpeed and whatsmeow
+
+Emitted for all incoming events from the LightSpeed (regular messages) and whatsmeow (E2EE) channels. This is useful for debugging or accessing raw event data that may not be processed by standard event handlers.
+
+```typescript
+client.on('raw', (data) => {
+    console.log(`Raw event from ${data.from}: ${data.type}`)
+    console.log(data.data)
+})
+```
+
+__Data object__
+
+* `from`: `'lightspeed'` | `'whatsmeow'` - Source channel of the event
+* `type`: string - Name of the event type (e.g., `"Event_Ready"`, `"FBMessage"`)
+* `data`: unknown - Raw event data (structure depends on the source)
+
+__Event sources__
+
+| Source | Description |
+|--------|-------------|
+| `lightspeed` | Events from LightSpeed protocol (regular Messenger) |
+| `whatsmeow` | Events from whatsmeow library (E2EE via WhatsApp protocol) |
+
+__Note__
+
+This event is emitted before the standard event handlers process the event. The raw data structure may vary depending on the source and event type. Use this for debugging or handling events not explicitly supported by the library.
+
+---
+
 # Types
 
 ## Cookies
@@ -1734,22 +1769,41 @@ interface Cookies {
 }
 ```
 
-## Message
+## BaseMessage
+
+Base interface shared by regular and E2EE messages.
 
 ```typescript
-interface Message {
-    id: string
-    threadId: number
-    senderId: number
-    text: string
-    timestampMs: number
-    isE2EE?: boolean
-    chatJid?: string
-    senderJid?: string
+interface BaseMessage {
+    id: string              // Message ID
+    threadId: number        // Thread ID (Facebook numeric ID)
+    senderId: number        // Sender's Facebook ID
+    text: string            // Message text content
+    timestampMs: number     // Timestamp in milliseconds
     attachments?: Attachment[]
     replyTo?: ReplyTo
     mentions?: Mention[]
-    isAdminMsg?: boolean
+}
+```
+
+## Message
+
+Regular message (non-E2EE). Extends [BaseMessage](#basemessage). Received via the `message` event.
+
+```typescript
+interface Message extends BaseMessage {
+    isAdminMsg?: boolean    // Whether this is an admin/system message
+}
+```
+
+## E2EEMessage
+
+End-to-end encrypted message. Extends [BaseMessage](#basemessage). Received via the `e2eeMessage` event.
+
+```typescript
+interface E2EEMessage extends BaseMessage {
+    chatJid: string         // Chat JID (required for E2EE operations)
+    senderJid: string       // Sender JID (required for E2EE operations)
 }
 ```
 

DOCS_VI.md

@@ -78,6 +78,7 @@
   * [`disconnected`](#event-disconnected) 🔵🟢
   * [`error`](#event-error) 🔵🟢
   * [`deviceDataChanged`](#event-deviceDataChanged) 🟢
+  * [`raw`](#event-raw) 🔵🟢
 * [Types](#types)
 
 ---
@@ -1370,6 +1371,7 @@ if (attachment.stickerId === THUMBS_UP_STICKER_IDS.LARGE) {
 | `e2eeReceipt` | ❌ | 🟢 | Tin nhắn đã đọc (E2EE) |
 | `e2eeConnected` | ❌ | 🟢 | Kết nối E2EE thành công |
 | `deviceDataChanged` | ❌ | 🟢 | Device data thay đổi |
+| `raw` | 🔵 | 🟢 | Event thô từ LightSpeed/whatsmeow |
 | `fullyReady` | 🔵 | 🟢 | Client hoàn toàn sẵn sàng |
 | `disconnected` | 🔵 | 🟢 | Mất kết nối |
 | `error` | 🔵 | 🟢 | Có lỗi xảy ra |
@@ -1720,6 +1722,39 @@ Event này chỉ được phát ra khi bạn khởi tạo client với option `d
 
 ---
 
+<a name="event-raw"></a>
+## Event: 'raw'
+
+> 🔵🟢 **Cả Socket và E2EE** - Tất cả event thô từ LightSpeed và whatsmeow
+
+Phát ra cho tất cả các event đến từ kênh LightSpeed (tin nhắn thường) và whatsmeow (E2EE). Hữu ích cho việc debug hoặc truy cập dữ liệu event thô không được xử lý bởi các event handler tiêu chuẩn.
+
+```typescript
+client.on('raw', (data) => {
+    console.log(`Raw event từ ${data.from}: ${data.type}`)
+    console.log(data.data)
+})
+```
+
+__Data object__
+
+* `from`: `'lightspeed'` | `'whatsmeow'` - Kênh nguồn của event
+* `type`: string - Tên loại event (ví dụ: `"Event_Ready"`, `"FBMessage"`)
+* `data`: unknown - Dữ liệu event thô (cấu trúc phụ thuộc vào nguồn)
+
+__Nguồn event__
+
+| Nguồn | Mô tả |
+|--------|-------------|
+| `lightspeed` | Event từ giao thức LightSpeed (Messenger thường) |
+| `whatsmeow` | Event từ thư viện whatsmeow (E2EE qua giao thức WhatsApp) |
+
+__Lưu ý__
+
+Event này được phát ra trước khi các event handler tiêu chuẩn xử lý event. Cấu trúc dữ liệu thô có thể thay đổi tùy thuộc vào nguồn và loại event. Sử dụng để debug hoặc xử lý các event không được thư viện hỗ trợ rõ ràng.
+
+---
+
 # Types
 
 ## Cookies
@@ -1734,22 +1769,41 @@ interface Cookies {
 }
 ```
 
-## Message
+## BaseMessage
+
+Interface cơ sở dùng chung cho tin nhắn thường và E2EE.
 
 ```typescript
-interface Message {
-    id: string
-    threadId: number
-    senderId: number
-    text: string
-    timestampMs: number
-    isE2EE?: boolean
-    chatJid?: string
-    senderJid?: string
+interface BaseMessage {
+    id: string              // ID tin nhắn
+    threadId: number        // Thread ID (Facebook numeric ID)
+    senderId: number        // Facebook ID của người gửi
+    text: string            // Nội dung văn bản
+    timestampMs: number     // Timestamp tính bằng milliseconds
     attachments?: Attachment[]
     replyTo?: ReplyTo
     mentions?: Mention[]
-    isAdminMsg?: boolean
+}
+```
+
+## Message
+
+Tin nhắn thường (không E2EE). Kế thừa [BaseMessage](#basemessage). Nhận qua event `message`.
+
+```typescript
+interface Message extends BaseMessage {
+    isAdminMsg?: boolean    // Có phải tin nhắn hệ thống không
+}
+```
+
+## E2EEMessage
+
+Tin nhắn mã hóa đầu cuối. Kế thừa [BaseMessage](#basemessage). Nhận qua event `e2eeMessage`.
+
+```typescript
+interface E2EEMessage extends BaseMessage {
+    chatJid: string         // Chat JID (bắt buộc cho các thao tác E2EE)
+    senderJid: string       // Sender JID (bắt buộc cho các thao tác E2EE)
 }
 ```
 

bridge-go/bridge/events.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"net/url"
+	"reflect"
 	"strconv"
 	"strings"
 	"time"
@@ -33,22 +34,23 @@ const (
 type EventType string
 
 const (
-	EventTypeReady          EventType = "ready"
-	EventTypeReconnected    EventType = "reconnected"
-	EventTypeDisconnected   EventType = "disconnected"
-	EventTypeError          EventType = "error"
-	EventTypeMessage        EventType = "message"
-	EventTypeMessageEdit    EventType = "messageEdit"
-	EventTypeMessageUnsend  EventType = "messageUnsend"
-	EventTypeReaction       EventType = "reaction"
-	EventTypeTyping         EventType = "typing"
-	EventTypePresence       EventType = "presence"
-	EventTypeReadReceipt    EventType = "readReceipt"
-	EventTypeE2EEConnected  EventType = "e2eeConnected"
-	EventTypeE2EEMessage    EventType = "e2eeMessage"
-	EventTypeE2EEReaction   EventType = "e2eeReaction"
-	EventTypeE2EEReceipt    EventType = "e2eeReceipt"
-	EventDeviceDataChanged  EventType = "deviceDataChanged"
+	EventTypeReady         EventType = "ready"
+	EventTypeReconnected   EventType = "reconnected"
+	EventTypeDisconnected  EventType = "disconnected"
+	EventTypeError         EventType = "error"
+	EventTypeRaw           EventType = "raw"
+	EventTypeMessage       EventType = "message"
+	EventTypeMessageEdit   EventType = "messageEdit"
+	EventTypeMessageUnsend EventType = "messageUnsend"
+	EventTypeReaction      EventType = "reaction"
+	EventTypeTyping        EventType = "typing"
+	EventTypePresence      EventType = "presence"
+	EventTypeReadReceipt   EventType = "readReceipt"
+	EventTypeE2EEConnected EventType = "e2eeConnected"
+	EventTypeE2EEMessage   EventType = "e2eeMessage"
+	EventTypeE2EEReaction  EventType = "e2eeReaction"
+	EventTypeE2EEReceipt   EventType = "e2eeReceipt"
+	EventDeviceDataChanged EventType = "deviceDataChanged"
 )
 
 // Event represents a generic event
@@ -118,16 +120,13 @@ type Mention struct {
 	Type   string `json:"type,omitempty"` // "user", "page", "group"
 }
 
-// Message represents a message
+// Message represents a regular (non-E2EE) message
 type Message struct {
 	ID          string        `json:"id"`
 	ThreadID    int64         `json:"threadId"`
 	SenderID    int64         `json:"senderId"`
 	Text        string        `json:"text"`
 	TimestampMs int64         `json:"timestampMs"`
-	IsE2EE      bool          `json:"isE2EE,omitempty"`
-	ChatJID     string        `json:"chatJid,omitempty"`
-	SenderJID   string        `json:"senderJid,omitempty"`
 	Attachments []*Attachment `json:"attachments,omitempty"`
 	ReplyTo     *ReplyTo      `json:"replyTo,omitempty"`
 	Mentions    []*Mention    `json:"mentions,omitempty"`
@@ -173,10 +172,29 @@ type ErrorEvent struct {
 	Code    int    `json:"code,omitempty"`
 }
 
-// E2EEMessage represents an E2EE message
+// RawEventSource represents the source of a raw event
+type RawEventSource string
+
+const (
+	RawEventSourceLightSpeed RawEventSource = "lightspeed" // LightSpeed events (non-E2EE)
+	RawEventSourceWhatsmeow  RawEventSource = "whatsmeow"  // WhatsApp/WhatsMe events (E2EE)
+)
+
+// RawEvent represents a raw event from internal sources
+// This is useful for debugging or handling events not explicitly supported
+type RawEvent struct {
+	// From indicates the source of the event
+	From RawEventSource `json:"from"`
+	// Type is the Go type name of the original event
+	Type string `json:"type"`
+	// Data contains the raw event data (JSON serialized)
+	Data interface{} `json:"data"`
+}
+
+// E2EEMessage represents an end-to-end encrypted message
 type E2EEMessage struct {
 	ID          string        `json:"id"`
-	ThreadID    int64         `json:"threadId"` // For compatibility with regular messages
+	ThreadID    int64         `json:"threadId"`
 	ChatJID     string        `json:"chatJid"`
 	SenderJID   string        `json:"senderJid"`
 	SenderID    int64         `json:"senderId"`
@@ -185,11 +203,29 @@ type E2EEMessage struct {
 	Attachments []*Attachment `json:"attachments,omitempty"`
 	ReplyTo     *ReplyTo      `json:"replyTo,omitempty"`
 	Mentions    []*Mention    `json:"mentions,omitempty"`
-	DebugType   string        `json:"debugType,omitempty"` // Debug: raw message type from protobuf
+}
+
+// getEventTypeName returns the type name of an event
+func getEventTypeName(evt any) string {
+	if evt == nil {
+		return "nil"
+	}
+	t := reflect.TypeOf(evt)
+	if t.Kind() == reflect.Ptr {
+		return t.Elem().Name()
+	}
+	return t.Name()
 }
 
 // handleEvent handles messagix events
 func (c *Client) handleEvent(ctx context.Context, evt any) {
+	// Emit raw event for all incoming LightSpeed events
+	c.emitEvent(EventTypeRaw, &RawEvent{
+		From: RawEventSourceLightSpeed,
+		Type: getEventTypeName(evt),
+		Data: evt,
+	})
+
 	switch e := evt.(type) {
 	case *messagix.Event_Ready:
 		c.emitEvent(EventTypeReady, map[string]any{
@@ -616,6 +652,13 @@ func (c *Client) convertBlobAttachment(blob *table.LSInsertBlobAttachment) *Atta
 
 // handleE2EEEvent handles WhatsApp E2EE events
 func (c *Client) handleE2EEEvent(evt interface{}) {
+	// Emit raw event for all incoming whatsmeow events
+	c.emitEvent(EventTypeRaw, &RawEvent{
+		From: RawEventSourceWhatsmeow,
+		Type: getEventTypeName(evt),
+		Data: evt,
+	})
+
 	switch e := evt.(type) {
 	case *events.Connected:
 		c.emitEvent(EventTypeE2EEConnected, nil)
@@ -1027,13 +1070,9 @@ func (c *Client) extractE2EEMessage(e *events.FBMessage, senderID int64) *E2EEMe
 	}
 
 	if e.Message == nil {
-		msg.DebugType = "nil"
 		return msg
 	}
 
-	// Set debug type from actual message type
-	msg.DebugType = fmt.Sprintf("%T", e.Message)
-
 	// Extract from ConsumerApplication
 	if ca, ok := e.Message.(*waConsumerApplication.ConsumerApplication); ok {
 		if p := ca.GetPayload(); p != nil {
@@ -1162,7 +1201,6 @@ func (c *Client) extractE2EEMessage(e *events.FBMessage, senderID int64) *E2EEMe
 
 		// Try Content first (link shares, etc.)
 		if content := payload.GetContent(); content != nil {
-			msg.DebugType = fmt.Sprintf("%T -> Content/%T", e.Message, content.GetContent())
 			// ExtendedContentMessage - used for link shares and location sharing
 			if extMsg := content.GetExtendedContentMessage(); extMsg != nil {
 				targetType := extMsg.GetTargetType()