@theowlops/channelhub 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheOwlOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+<div align="center">
+
+# 🌐 ChannelHub
+
+*The Universal Multi-Channel Messaging SDK for AI Agents & Modern Applications*
+
+[![npm version](https://img.shields.io/npm/v/@theowlops/channelhub?color=blue&style=flat-square)](https://www.npmjs.com/package/@theowlops/channelhub)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+[![Bun](https://img.shields.io/badge/Runtime-Bun%20%7C%20Node%20%7C%20Deno-black?style=flat-square)](https://bun.sh)
+[![AI Native](https://img.shields.io/badge/AI%20Agent-Universal%20MCP%20%7C%20REST-purple?style=flat-square)](#ai-agent-integrations)
+
+Unified messaging protocol & channel adapters across **Zalo**, **Telegram**, **Discord**, and **Slack**. Connect once, listen everywhere, reply with any AI framework.
+
+[Highlights](#highlights) • [Quick Start](#quick-start) • [Channel Adapters](#channel-adapters) • [AI Integrations & MCP](#ai-agent-integrations) • [REST / SSE Webhook](#webhook-bridge)
+
+</div>
+
+---
+
+## Highlights
+
+- **Universal Multi-Channel Protocol**: Single `IChannelAdapter` contract and normalized `UnifiedMessage` across Zalo (Personal & OA), Telegram, Discord, and Slack.
+- **AI Agent Native**: First-class support for Model Context Protocol (MCP), Hermes Agent, OpenClaw, LangChain, CrewAI, and n8n/Dify.
+- **Zero Heavy Core**: Lightweight event-driven architecture running on standard Web APIs and `node:events`. Zero bloat.
+- **Universal Packaging**: Dual ESM & CommonJS outputs with complete TypeScript declaration maps (`.d.ts`).
+- **Backward Compatible**: Retains 100% full API compatibility with existing `@theowlops/zalohub` personal & OA bot callers.
+
+---
+
+## Installation
+
+```bash
+# bun (recommended)
+bun add @theowlops/channelhub
+
+# npm
+npm install @theowlops/channelhub
+
+# pnpm
+pnpm add @theowlops/channelhub
+```
+
+---
+
+## Quick Start
+
+### 1. Multi-Channel AI Bot (Native Event Loop)
+
+```ts
+import { ChannelHub } from "@theowlops/channelhub";
+import { ZaloChannelAdapter } from "@theowlops/channelhub/zalo";
+import { TelegramChannelAdapter } from "@theowlops/channelhub/telegram";
+
+const hub = new ChannelHub();
+
+// Register channels
+hub.register(new ZaloChannelAdapter({ credentialsPath: "./credentials.json" }));
+hub.register(new TelegramChannelAdapter({ botToken: process.env.TELEGRAM_BOT_TOKEN! }));
+
+// Single unified message handler for all platforms
+hub.onMessage(async (ctx) => {
+  console.log(`[${ctx.message.channel}] ${ctx.message.sender.name}: ${ctx.message.content.text}`);
+
+  // Auto-reply back to the originating chat
+  if (ctx.message.content.text === "/ping") {
+    await ctx.reply("Pong from ChannelHub! 🚀");
+  }
+
+  // React with emoji
+  await ctx.react("❤️");
+});
+
+await hub.start();
+```
+
+---
+
+## Channel Adapters
+
+### Zalo Adapter (`@theowlops/channelhub/zalo`)
+Supports both reverse-engineered personal web session (`zca-js`) and Official Account (OA) OpenAPI v3.
+
+```ts
+import { ZaloChannelAdapter } from "@theowlops/channelhub/zalo";
+
+const zalo = new ZaloChannelAdapter({
+  credentialsPath: "./credentials.json", // Generated via `channelhub login zalo`
+});
+```
+
+### Telegram Adapter (`@theowlops/channelhub/telegram`)
+Zero-dependency Telegram bot engine with automatic long-polling or webhook integration.
+
+```ts
+import { TelegramChannelAdapter } from "@theowlops/channelhub/telegram";
+
+const tele = new TelegramChannelAdapter({
+  botToken: "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
+});
+```
+
+### Discord Adapter (`@theowlops/channelhub/discord`)
+Ultra-lightweight HTTP REST & gateway parser for Discord bots.
+
+```ts
+import { DiscordChannelAdapter } from "@theowlops/channelhub/discord";
+
+const discord = new DiscordChannelAdapter({
+  botToken: process.env.DISCORD_BOT_TOKEN!,
+});
+```
+
+### Slack Adapter (`@theowlops/channelhub/slack`)
+Socket-mode & Event API adapter for workspace enterprise bots.
+
+```ts
+import { SlackChannelAdapter } from "@theowlops/channelhub/slack";
+
+const slack = new SlackChannelAdapter({
+  botToken: process.env.SLACK_BOT_TOKEN!,
+});
+```
+
+---
+
+## AI Agent Integrations
+
+### Model Context Protocol (MCP) Server
+Expose ChannelHub directly to **Claude Desktop**, **Cursor**, **Codex**, or **Hermes Agent**:
+
+```ts
+import { ChannelHub } from "@theowlops/channelhub";
+import { getChannelHubMcpTools, handleChannelHubMcpCall } from "@theowlops/channelhub/mcp";
+
+// Tools provided:
+// - channelhub_list_channels
+// - channelhub_send_message
+// - channelhub_add_reaction
+```
+
+### Webhook Bridge (REST & Server-Sent Events)
+Run a local REST & SSE server for **n8n**, **Dify**, or **Flowise**:
+
+```ts
+import { ChannelHub } from "@theowlops/channelhub";
+import { WebhookBridge } from "@theowlops/channelhub/webhook";
+
+const hub = new ChannelHub();
+const bridge = new WebhookBridge(hub, { port: 8788 });
+
+await hub.start();
+await bridge.start();
+
+// Endpoints available:
+// GET  http://localhost:8788/health
+// GET  http://localhost:8788/channels
+// POST http://localhost:8788/send      { "channel": "telegram", "chatId": "...", "text": "Hi" }
+// GET  http://localhost:8788/events    (SSE real-time stream of all incoming messages)
+```
+
+---
+
+## Subpath Imports
+
+```ts
+import { ChannelHub, BaseChannel, type UnifiedMessage } from "@theowlops/channelhub";
+import { ZaloChannelAdapter } from "@theowlops/channelhub/zalo";
+import { TelegramChannelAdapter } from "@theowlops/channelhub/telegram";
+import { DiscordChannelAdapter } from "@theowlops/channelhub/discord";
+import { SlackChannelAdapter } from "@theowlops/channelhub/slack";
+import { getChannelHubMcpTools } from "@theowlops/channelhub/mcp";
+import { WebhookBridge } from "@theowlops/channelhub/webhook";
+```
+
+---
+
+## License
+
+MIT © [TheOwlOps](https://github.com/TheOwlOps)

package/bin/cli.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const command = args[0] || "help";
+
+switch (command) {
+  case "login": {
+    console.log("[ZaloHub CLI] Quet ma QR de dang nhap...");
+    import("../scripts/login_personal.ts");
+    break;
+  }
+  case "start": {
+    console.log("[ZaloHub CLI] Khoi dong Bot...");
+    import("../src/index.ts");
+    break;
+  }
+  case "help":
+  default: {
+    console.log(`
+ZaloHub CLI - SDK & Bot Manager
+
+Usage:
+  zalohub <command>
+
+Commands:
+  login      Quet ma QR dang nhap tai khoan ca nhan
+  start      Khoi dong Bot service
+  help       Xem huong dan
+`);
+    break;
+  }
+}

package/dist/bridges/mcp/index.d.ts

@@ -0,0 +1,14 @@
+import type { ChannelHub } from "../../core/hub";
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export declare function getChannelHubMcpTools(): McpToolDefinition[];
+export declare function handleChannelHubMcpCall(hub: ChannelHub, toolName: string, args: Record<string, any>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/bridges/mcp/index.js

@@ -0,0 +1,96 @@
+// src/bridges/mcp/index.ts
+function getChannelHubMcpTools() {
+  return [
+    {
+      name: "channelhub_list_channels",
+      description: "List all active channels registered in ChannelHub (e.g. zalo, telegram, discord, slack).",
+      parameters: {
+        type: "object",
+        properties: {}
+      }
+    },
+    {
+      name: "channelhub_send_message",
+      description: "Send a text message or reply to a specific chat on a registered channel.",
+      parameters: {
+        type: "object",
+        required: ["channel", "chatId", "text"],
+        properties: {
+          channel: {
+            type: "string",
+            description: "Channel name (e.g. 'zalo', 'telegram', 'discord', 'slack')"
+          },
+          chatId: {
+            type: "string",
+            description: "Target chat/thread/channel ID"
+          },
+          text: {
+            type: "string",
+            description: "Message body text"
+          },
+          replyToId: {
+            type: "string",
+            description: "Optional message ID to reply to"
+          }
+        }
+      }
+    },
+    {
+      name: "channelhub_add_reaction",
+      description: "React to a message with an emoji.",
+      parameters: {
+        type: "object",
+        required: ["channel", "chatId", "messageId", "emoji"],
+        properties: {
+          channel: { type: "string" },
+          chatId: { type: "string" },
+          messageId: { type: "string" },
+          emoji: { type: "string" }
+        }
+      }
+    }
+  ];
+}
+async function handleChannelHubMcpCall(hub, toolName, args) {
+  try {
+    switch (toolName) {
+      case "channelhub_list_channels": {
+        const channels = hub.listChannels();
+        return {
+          content: [{ type: "text", text: JSON.stringify({ channels }, null, 2) }]
+        };
+      }
+      case "channelhub_send_message": {
+        const ch = hub.getChannel(args.channel);
+        if (!ch)
+          throw new Error(`Channel '${args.channel}' not found or not active.`);
+        const res = await ch.sendText(args.chatId, args.text, { replyToId: args.replyToId });
+        return {
+          content: [{ type: "text", text: JSON.stringify(res, null, 2) }]
+        };
+      }
+      case "channelhub_add_reaction": {
+        const ch = hub.getChannel(args.channel);
+        if (!ch)
+          throw new Error(`Channel '${args.channel}' not found.`);
+        if (!ch.addReaction)
+          throw new Error(`Channel '${args.channel}' does not support reactions.`);
+        await ch.addReaction(args.chatId, args.messageId, args.emoji);
+        return {
+          content: [{ type: "text", text: JSON.stringify({ success: true }) }]
+        };
+      }
+      default:
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: err.message || String(err) }]
+    };
+  }
+}
+export {
+  getChannelHubMcpTools,
+  handleChannelHubMcpCall
+};

package/dist/bridges/webhook/index.d.ts

@@ -0,0 +1,32 @@
+import type { ChannelHub } from "../../core/hub";
+export interface WebhookBridgeConfig {
+    port?: number;
+    host?: string;
+    pathPrefix?: string;
+}
+/**
+ * HTTP / SSE bridge exposing ChannelHub over REST.
+ * Compatible with n8n, Dify, Flowise, LangChain custom tools, and plain curl.
+ *
+ * Endpoints:
+ *   GET  /health
+ *   GET  /channels
+ *   POST /send          { channel, chatId, text, replyToId? }
+ *   POST /react         { channel, chatId, messageId, emoji }
+ *   GET  /events        Server-Sent Events stream of inbound UnifiedMessages
+ */
+export declare class WebhookBridge {
+    private hub;
+    private config;
+    private server;
+    private sseClients;
+    constructor(hub: ChannelHub, config?: WebhookBridgeConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private path;
+    private handle;
+    private handleSse;
+    private broadcastSse;
+    private json;
+    private readJson;
+}

package/dist/bridges/webhook/index.js

@@ -0,0 +1,123 @@
+// src/bridges/webhook/index.ts
+import { createServer } from "node:http";
+
+class WebhookBridge {
+  hub;
+  config;
+  server = null;
+  sseClients = new Set;
+  constructor(hub, config = {}) {
+    this.hub = hub;
+    this.config = {
+      port: config.port ?? 8788,
+      host: config.host ?? "0.0.0.0",
+      pathPrefix: config.pathPrefix ?? ""
+    };
+    hub.onMessage(async (ctx) => {
+      this.broadcastSse(ctx.message);
+    });
+  }
+  async start() {
+    this.server = createServer((req, res) => this.handle(req, res));
+    await new Promise((resolve) => {
+      this.server.listen(this.config.port, this.config.host, () => resolve());
+    });
+  }
+  async stop() {
+    for (const client of this.sseClients) {
+      client.end();
+    }
+    this.sseClients.clear();
+    if (this.server) {
+      await new Promise((resolve, reject) => {
+        this.server.close((err) => err ? reject(err) : resolve());
+      });
+      this.server = null;
+    }
+  }
+  path(req) {
+    const url = req.url || "/";
+    const bare = url.split("?")[0];
+    return bare.startsWith(this.config.pathPrefix) ? bare.slice(this.config.pathPrefix.length) || "/" : bare;
+  }
+  async handle(req, res) {
+    const p = this.path(req);
+    try {
+      if (req.method === "GET" && p === "/health") {
+        return this.json(res, 200, { ok: true });
+      }
+      if (req.method === "GET" && p === "/channels") {
+        return this.json(res, 200, { channels: this.hub.listChannels() });
+      }
+      if (req.method === "POST" && p === "/send") {
+        const body = await this.readJson(req);
+        const ch = this.hub.getChannel(body.channel);
+        if (!ch)
+          return this.json(res, 404, { error: `Channel '${body.channel}' not found` });
+        const result = await ch.sendText(body.chatId, body.text, { replyToId: body.replyToId });
+        return this.json(res, 200, result);
+      }
+      if (req.method === "POST" && p === "/react") {
+        const body = await this.readJson(req);
+        const ch = this.hub.getChannel(body.channel);
+        if (!ch)
+          return this.json(res, 404, { error: `Channel '${body.channel}' not found` });
+        if (!ch.addReaction)
+          return this.json(res, 400, { error: "Channel does not support reactions" });
+        await ch.addReaction(body.chatId, body.messageId, body.emoji);
+        return this.json(res, 200, { success: true });
+      }
+      if (req.method === "GET" && p === "/events") {
+        return this.handleSse(res);
+      }
+      this.json(res, 404, { error: "Not found" });
+    } catch (err) {
+      this.json(res, 500, { error: err.message || String(err) });
+    }
+  }
+  handleSse(res) {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive"
+    });
+    res.write(`data: ${JSON.stringify({ type: "connected" })}
+
+`);
+    this.sseClients.add(res);
+    res.on("close", () => this.sseClients.delete(res));
+  }
+  broadcastSse(msg) {
+    const payload = `data: ${JSON.stringify(msg)}
+
+`;
+    for (const client of this.sseClients) {
+      client.write(payload);
+    }
+  }
+  json(res, status, body) {
+    const data = JSON.stringify(body);
+    res.writeHead(status, {
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(data)
+    });
+    res.end(data);
+  }
+  readJson(req) {
+    return new Promise((resolve, reject) => {
+      const chunks = [];
+      req.on("data", (c) => chunks.push(c));
+      req.on("end", () => {
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"));
+        } catch (err) {
+          reject(err);
+        }
+      });
+      req.on("error", reject);
+    });
+  }
+}
+export {
+  WebhookBridge
+};

package/dist/channels/discord/adapter.d.ts

@@ -0,0 +1,24 @@
+import { BaseChannel } from "../../core/adapter";
+import type { ChannelType, MediaPayload, SendOptions, SentMessageResult, UnifiedMessage } from "../../core/types";
+export interface DiscordAdapterConfig {
+    botToken: string;
+    intents?: number;
+    autoStart?: boolean;
+}
+/**
+ * Lightweight Discord adapter using Discord HTTP REST API.
+ * Gateway WS is optional — messages can be pushed via normalizeEvent() for webhook/gateway bridges.
+ */
+export declare class DiscordChannelAdapter extends BaseChannel {
+    readonly name: ChannelType;
+    private config;
+    private apiBase;
+    constructor(config: DiscordAdapterConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    normalizeEvent(event: any): UnifiedMessage | null;
+    private callApi;
+    sendText(chatId: string, text: string, options?: SendOptions): Promise<SentMessageResult>;
+    sendMedia(chatId: string, media: MediaPayload, options?: SendOptions): Promise<SentMessageResult>;
+    addReaction(chatId: string, messageId: string, emoji: string): Promise<void>;
+}

package/dist/channels/discord/index.d.ts

@@ -0,0 +1 @@
+export * from "./adapter";

package/dist/channels/discord/index.js

@@ -0,0 +1,130 @@
+// src/core/adapter.ts
+import { EventEmitter } from "node:events";
+
+class BaseChannel extends EventEmitter {
+  _connected = false;
+  isConnected() {
+    return this._connected;
+  }
+  setConnected(value) {
+    const changed = this._connected !== value;
+    this._connected = value;
+    if (changed) {
+      this.emit("status", value ? "connected" : "disconnected");
+    }
+  }
+}
+
+// src/channels/discord/adapter.ts
+class DiscordChannelAdapter extends BaseChannel {
+  name = "discord";
+  config;
+  apiBase = "https://discord.com/api/v10";
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async connect() {
+    if (!this.config.botToken)
+      throw new Error("Discord botToken is required.");
+    await this.callApi("GET", "/users/@me");
+    this.setConnected(true);
+  }
+  async disconnect() {
+    this.setConnected(false);
+  }
+  normalizeEvent(event) {
+    if (!event || event.type !== 0 && !event.content && !event.author) {
+      if (!event?.content && !event?.d?.content)
+        return null;
+    }
+    const msg = event.d || event;
+    if (!msg.content && !msg.attachments?.length)
+      return null;
+    if (msg.author?.bot)
+      return null;
+    const isDm = !msg.guild_id;
+    return {
+      id: String(msg.id),
+      channel: "discord",
+      sender: {
+        id: String(msg.author?.id ?? ""),
+        name: msg.author?.global_name || msg.author?.username,
+        username: msg.author?.username,
+        isBot: Boolean(msg.author?.bot),
+        avatarUrl: msg.author?.avatar ? `https://cdn.discordapp.com/avatars/${msg.author.id}/${msg.author.avatar}.png` : undefined
+      },
+      chat: {
+        id: String(msg.channel_id),
+        type: isDm ? "dm" : "channel",
+        title: undefined
+      },
+      content: {
+        text: msg.content || "",
+        attachments: (msg.attachments || []).map((a) => ({
+          type: a.content_type?.startsWith("image/") ? "image" : a.content_type?.startsWith("video/") ? "video" : "file",
+          url: a.url,
+          filename: a.filename,
+          mimeType: a.content_type,
+          size: a.size
+        })),
+        replyToId: msg.message_reference?.message_id ? String(msg.message_reference.message_id) : undefined
+      },
+      raw: event,
+      timestamp: msg.timestamp ? Date.parse(msg.timestamp) : Date.now()
+    };
+  }
+  async callApi(method, path, body) {
+    const res = await fetch(`${this.apiBase}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bot ${this.config.botToken}`,
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : undefined
+    });
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`Discord API ${method} ${path} failed: ${res.status} ${errText}`);
+    }
+    if (res.status === 204)
+      return null;
+    return res.json();
+  }
+  async sendText(chatId, text, options) {
+    const payload = { content: text };
+    if (options?.replyToId) {
+      payload.message_reference = { message_id: options.replyToId };
+    }
+    const res = await this.callApi("POST", `/channels/${chatId}/messages`, payload);
+    return {
+      messageId: String(res.id),
+      chatId,
+      timestamp: Date.parse(res.timestamp) || Date.now()
+    };
+  }
+  async sendMedia(chatId, media, options) {
+    const payload = {
+      content: media.caption || ""
+    };
+    if (typeof media.source === "string") {
+      payload.embeds = [{ image: { url: media.source } }];
+    }
+    if (options?.replyToId) {
+      payload.message_reference = { message_id: options.replyToId };
+    }
+    const res = await this.callApi("POST", `/channels/${chatId}/messages`, payload);
+    return {
+      messageId: String(res.id),
+      chatId,
+      timestamp: Date.parse(res.timestamp) || Date.now()
+    };
+  }
+  async addReaction(chatId, messageId, emoji) {
+    const encoded = encodeURIComponent(emoji);
+    await this.callApi("PUT", `/channels/${chatId}/messages/${messageId}/reactions/${encoded}/@me`);
+  }
+}
+export {
+  DiscordChannelAdapter
+};

package/dist/channels/slack/adapter.d.ts

@@ -0,0 +1,20 @@
+import { BaseChannel } from "../../core/adapter";
+import type { ChannelType, MediaPayload, SendOptions, SentMessageResult, UnifiedMessage } from "../../core/types";
+export interface SlackAdapterConfig {
+    botToken: string;
+    appToken?: string;
+    signingSecret?: string;
+}
+export declare class SlackChannelAdapter extends BaseChannel {
+    readonly name: ChannelType;
+    private config;
+    private apiBase;
+    constructor(config: SlackAdapterConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    normalizeEvent(event: any): UnifiedMessage | null;
+    private callApi;
+    sendText(chatId: string, text: string, options?: SendOptions): Promise<SentMessageResult>;
+    sendMedia(chatId: string, media: MediaPayload, options?: SendOptions): Promise<SentMessageResult>;
+    addReaction(chatId: string, messageId: string, emoji: string): Promise<void>;
+}

package/dist/channels/slack/index.d.ts

@@ -0,0 +1 @@
+export * from "./adapter";