@gloablehive/celphone-wechat-plugin 1.0.0

package/dist/src/channel.js

@@ -0,0 +1,334 @@
+/**
+ * WorkPhone WeChat Channel Plugin for OpenClaw
+ *
+ * This channel plugin connects OpenClaw to WorkPhone's WeChat API,
+ * enabling sending and receiving WeChat messages through the WorkPhone platform.
+ *
+ * IMPORTANT - Human Account Model:
+ * Unlike Telegram/WhatsApp bots, this connects to a real human WeChat account.
+ * The agent communicates with ALL friends and groups under that WeChat account,
+ * not just one DM context. This is "human mode" vs "bot mode".
+ *
+ * Includes Local Cache:
+ * - Per-account, per-user/conversation MD files
+ * - YAML frontmatter (aligned with Claude Code)
+ * - MEMORY.md indexing
+ * - 4-layer compression
+ * - AI summary extraction
+ * - SAAS connectivity + offline fallback
+ * - Cloud sync
+ */
+import { createChatChannelPlugin, createChannelPluginBase, } from "openclaw/plugin-sdk/core";
+import { createWorkPhoneClient } from "./client.js";
+// Import cache modules
+import { createCacheManager, } from "./cache/index.js";
+// Cache manager instance (lazy initialized)
+let cacheManager = null;
+/**
+ * Get or create cache manager
+ */
+function getCacheManager(cfg) {
+    if (cacheManager)
+        return cacheManager;
+    const section = cfg.channels?.["celphone-wechat"];
+    const accounts = (section?.accounts || []);
+    // If no accounts configured, create default from main config
+    if (accounts.length === 0 && section?.wechatAccountId) {
+        accounts.push({
+            accountId: section.accountId || 'default',
+            wechatAccountId: section.wechatAccountId,
+            wechatId: section.wechatId || section.wechatAccountId,
+            nickName: section.nickName || 'WeChat User',
+            enabled: true,
+        });
+    }
+    const basePath = globalThis?.process?.env?.OPENCLAW_CACHE_PATH
+        || '~/.openclaw/channels/celphone-wechat';
+    cacheManager = createCacheManager({
+        basePath,
+        accounts,
+        saasConfig: section?.saas ? {
+            apiBaseUrl: section.saas.apiBaseUrl,
+            apiKey: section.saas.apiKey,
+            timeout: section.saas.timeout || 5000,
+        } : undefined,
+        syncConfig: section?.sync ? {
+            databaseUrl: section.sync.databaseUrl,
+            syncMode: section.sync.syncMode || 'interval',
+            syncIntervalMs: section.sync.syncIntervalMs || 5 * 60 * 1000,
+        } : undefined,
+    });
+    // Initialize cache manager
+    cacheManager.init().catch(err => {
+        console.error('[CelPhoneWeChat] Cache manager init failed:', err);
+    });
+    return cacheManager;
+}
+/**
+ * Resolve account from OpenClaw config
+ *
+ * Note: This is a "human account" model - the WeChat account represents
+ * a real person with all their friends and groups, not a bot.
+ */
+function resolveAccount(cfg, accountId) {
+    const section = cfg.channels?.["celphone-wechat"];
+    const apiKey = section?.apiKey;
+    const baseUrl = section?.baseUrl || "https://api.workphone.example.com";
+    const wechatAccountId = section?.wechatAccountId;
+    if (!apiKey) {
+        throw new Error("celphone-wechat: apiKey is required");
+    }
+    if (!wechatAccountId) {
+        throw new Error("celphone-wechat: wechatAccountId is required (the WeChat account to use)");
+    }
+    return {
+        accountId: accountId ?? null,
+        apiKey,
+        baseUrl,
+        wechatAccountId,
+        wechatId: section?.wechatId || wechatAccountId, // Actual WeChat ID (wxid_xxx)
+        nickName: section?.nickName || "WeChat User", // Display name
+        allowFrom: section?.allowFrom ?? [],
+        dmPolicy: section?.dmSecurity,
+    };
+}
+/**
+ * Create the channel plugin
+ */
+export const celPhoneWeChatPlugin = createChatChannelPlugin({
+    base: createChannelPluginBase({
+        id: "celphone-wechat",
+        setup: {
+            resolveAccount,
+            inspectAccount(cfg, accountId) {
+                const section = cfg.channels?.["celphone-wechat"];
+                const hasApiKey = Boolean(section?.apiKey);
+                return {
+                    enabled: hasApiKey,
+                    configured: hasApiKey,
+                    tokenStatus: hasApiKey ? "available" : "missing",
+                };
+            },
+        },
+    }),
+    // DM security: who can message the bot
+    security: {
+        dm: {
+            channelKey: "celphone-wechat",
+            resolvePolicy: (account) => account.dmPolicy,
+            resolveAllowFrom: (account) => account.allowFrom,
+            defaultPolicy: "allowlist", // Default to allowlist for security
+        },
+    },
+    // Pairing: not currently supported for this channel
+    // WorkPhone WeChat doesn't have a standard pairing flow
+    // pairing: { ... },
+    // Threading: how replies are delivered
+    // For WeChat, replies go back to the same chat (friend or chatroom)
+    threading: {
+        topLevelReplyToMode: "reply", // Reply to the last message in the thread
+    },
+    // Outbound: send messages to WeChat via WorkPhone API
+    //
+    // HUMAN ACCOUNT MODEL IMPORTANT:
+    // This channel connects to a real person's WeChat account.
+    // The agent needs to communicate with ALL their friends and groups,
+    // not just one conversation. We distinguish by conversation type:
+    // - DM (direct): friendWechatId in params.to
+    // - Group chat: chatroomId in params.to (detect by format or metadata)
+    outbound: {
+        attachedResults: {
+            // Send text - detect if DM or group based on conversation metadata
+            sendText: async (params) => {
+                const client = createWorkPhoneClient({
+                    baseUrl: params.account.baseUrl,
+                    apiKey: params.account.apiKey,
+                    accountId: params.account.accountId || undefined,
+                    wechatAccountId: params.account.wechatAccountId,
+                });
+                // Check if this is a group message (chatroom)
+                // Chatroom IDs typically start with certain prefix or have specific format
+                const isChatroom = params.metadata?.conversationType === 'group' ||
+                    (params.to && params.to.includes('@chatroom'));
+                let result;
+                if (isChatroom) {
+                    // Send to chatroom (group)
+                    result = await client.sendChatroomMessage({
+                        wechatAccountId: params.account.wechatAccountId,
+                        chatroomId: params.to,
+                        content: params.text,
+                        type: 'text',
+                    });
+                }
+                else {
+                    // Send to friend (DM)
+                    result = await client.sendFriendMessage({
+                        wechatAccountId: params.account.wechatAccountId,
+                        friendWechatId: params.to,
+                        content: params.text,
+                        type: 'text',
+                    });
+                }
+                return { messageId: result.messageId };
+            },
+            // Send media - also support both DM and group
+            sendMedia: async (params) => {
+                const client = createWorkPhoneClient({
+                    baseUrl: params.account.baseUrl,
+                    apiKey: params.account.apiKey,
+                    accountId: params.account.accountId || undefined,
+                    wechatAccountId: params.account.wechatAccountId,
+                });
+                const isChatroom = params.metadata?.conversationType === 'group' ||
+                    (params.to && params.to.includes('@chatroom'));
+                let result;
+                if (isChatroom) {
+                    result = await client.sendChatroomMessage({
+                        wechatAccountId: params.account.wechatAccountId,
+                        chatroomId: params.to,
+                        content: params.filePath || '',
+                        type: 'file',
+                    });
+                }
+                else {
+                    result = await client.sendFriendMessage({
+                        wechatAccountId: params.account.wechatAccountId,
+                        friendWechatId: params.to,
+                        content: params.filePath || '',
+                        type: 'file',
+                    });
+                }
+                return { messageId: result.messageId };
+            },
+        },
+        // Additional outbound handlers can be added here for:
+        // - sendLink: Send link cards
+        // - sendLocation: Send location
+        // - sendContact: Send contact card
+    },
+    // Additional capabilities
+    // - Describe the channel's message types and features
+    capabilities: {
+        supportedMessageTypes: [
+            "text",
+            "image",
+            "video",
+            "file",
+            "link",
+            "location",
+            "contact",
+        ],
+        maxAttachmentSize: 25 * 1024 * 1024, // 25MB
+        supportsMarkdown: false, // WeChat uses a limited markup
+        supportsHtml: false,
+        supportsEmoji: true,
+        supportsReactions: false, // WeChat doesn't support reactions
+        supportsThreads: true, // Can reply in chat
+        supportsEditing: false, // Cannot edit sent messages
+        supportsDeleting: false, // Cannot delete sent messages
+    },
+});
+/**
+ * Helper function to handle inbound webhook messages
+ * This should be called from your HTTP route handler
+ *
+ * Integrates with Cache Manager for:
+ * - Local MD file caching
+ * - User profile storage
+ * - Session memory
+ * - Cloud sync
+ * - Offline fallback
+ */
+export async function handleInboundMessage(api, payload, cfg) {
+    const { event, accountId, wechatAccountId, message, friendRequest } = payload;
+    if (event === 'message' && message) {
+        // Determine conversation type
+        const isChatroom = !!message.chatroomId;
+        const conversationId = isChatroom
+            ? message.chatroomId
+            : message.fromUser || message.toUser || '';
+        // Convert to cache format and store locally
+        if (cacheManager && accountId) {
+            try {
+                await cacheManager.onMessage({
+                    messageId: message.messageId,
+                    msgSvrId: message.msgSvrId,
+                    accountId: accountId,
+                    conversationType: isChatroom ? 'chatroom' : 'friend',
+                    conversationId,
+                    senderId: message.fromUser || '',
+                    content: message.content,
+                    messageType: message.type || 1,
+                    timestamp: message.timestamp || Date.now(),
+                    isSelf: message.isSelf || false,
+                    direction: message.isSelf ? 'outbound' : 'inbound',
+                });
+            }
+            catch (err) {
+                console.error('[CelPhoneWeChat] Cache write failed:', err);
+            }
+        }
+        // Convert WorkPhone message format to OpenClaw format
+        const openclawMessage = {
+            id: message.messageId,
+            rawId: message.msgSvrId || message.messageId,
+            conversation: {
+                type: isChatroom ? 'group' : 'dm',
+                id: conversationId,
+                chatroomId: isChatroom ? conversationId : undefined,
+            },
+            sender: {
+                id: message.fromUser || '',
+                platformId: message.wechatId,
+            },
+            content: {
+                type: message.type === 1 ? 'text' : 'media',
+                text: message.content,
+            },
+            timestamp: new Date(message.timestamp || Date.now()),
+            isSelf: message.isSelf || false,
+        };
+        // Dispatch to OpenClaw
+        await api.inbound.dispatchMessage(openclawMessage);
+    }
+    else if (event === 'friend_request' && friendRequest) {
+        // Handle friend request
+        await api.inbound.dispatchFriendRequest({
+            id: friendRequest.v1,
+            platformId: friendRequest.fromUser,
+            scene: friendRequest.scene,
+            ticket: friendRequest.ticket,
+            accountId,
+            wechatAccountId,
+        });
+    }
+}
+/**
+ * Get user profile from cache (for agent use)
+ */
+export async function getUserProfile(accountId, wechatId) {
+    if (!cacheManager)
+        return null;
+    return await cacheManager.getProfile(accountId, wechatId);
+}
+/**
+ * Update user profile in cache
+ */
+export async function updateUserProfile(accountId, wechatId, updates) {
+    if (!cacheManager)
+        return;
+    await cacheManager.updateProfile(accountId, wechatId, updates);
+}
+/**
+ * Get SAAS connection status
+ */
+export function getConnectionStatus() {
+    return cacheManager?.getConnectionStatus();
+}
+/**
+ * Check if system is online (SAAS connected)
+ */
+export function isOnline() {
+    return cacheManager?.isSAASOnline() ?? false;
+}
+export default celPhoneWeChatPlugin;

package/dist/src/client.d.ts

@@ -0,0 +1,280 @@
+/**
+ * WorkPhone WeChat API Client
+ *
+ * Interfaces with the WorkPhone API for sending/receiving WeChat messages
+ * Based on the Apifox API manual: data/apifox-workphone-3/
+ */
+export interface WorkPhoneConfig {
+    baseUrl: string;
+    apiKey: string;
+    accountId?: string;
+    wechatAccountId?: string;
+}
+export interface WeChatFriend {
+    wechatFriendId: string;
+    wechatId: string;
+    nickName: string;
+    remark: string;
+    avatar?: string;
+    label?: string[];
+    phones?: string[];
+}
+export interface WeChatChatroom {
+    wechatChatroomId: string;
+    chatroomId: string;
+    name: string;
+    ownerId: string;
+    memberCount: number;
+}
+export interface WeChatMessage {
+    messageId: string;
+    msgSvrId?: string;
+    wechatId: string;
+    content: string;
+    type: number;
+    timestamp: number;
+    isSelf: boolean;
+    fromUser?: string;
+    toUser?: string;
+}
+export interface SendMessageParams {
+    wechatAccountId: string;
+    toUser: string;
+    content: string;
+    type?: 'text' | 'image' | 'video' | 'file' | 'link' | 'card';
+}
+export interface SendMessageResult {
+    messageId: string;
+    msgSvrId?: string;
+    success: boolean;
+}
+export interface WebhookPayload {
+    event: 'message' | 'friend_request' | 'group_invite' | 'system';
+    accountId: string;
+    wechatAccountId: string;
+    message?: WeChatMessage;
+    friendRequest?: {
+        v1: string;
+        scene: number;
+        fromUser: string;
+        ticket?: string;
+    };
+    timestamp: number;
+}
+export declare class WorkPhoneWeChatClient {
+    private config;
+    constructor(config: WorkPhoneConfig);
+    private request;
+    /**
+     * Get all WeChat accounts for an account
+     * GET /api/v1/accounts/{accountId}/wechatAccounts
+     */
+    getWeChatAccounts(accountId: string): Promise<WeChatFriend[]>;
+    /**
+     * Get WeChat account info by wechatId
+     * GET /wp/api/v1/wechatAccounts/{wechatId}/byWechatId
+     */
+    getWeChatAccountById(wechatId: string): Promise<any>;
+    /**
+     * Get all friends for a WeChat account
+     * GET /wp/api/v1/wechatAccounts/{wechatAccountId}/friends
+     */
+    getFriends(wechatAccountId: string, options?: {
+        page?: number;
+        pageSize?: number;
+        labelId?: string;
+    }): Promise<{
+        list: WeChatFriend[];
+        total: number;
+    }>;
+    /**
+     * Search friends
+     * GET /wp/api/v1/wechatFriends
+     */
+    searchFriends(params: {
+        accountId?: string;
+        wechatAccountId?: string;
+        keyword?: string;
+    }): Promise<WeChatFriend[]>;
+    /**
+     * Get friend by ID
+     * GET /wp/api/v1/wechatFriends/{wechatFriendId}
+     */
+    getFriend(wechatFriendId: string): Promise<WeChatFriend>;
+    /**
+     * Add friend (send friend request)
+     * POST /wp/api/v1/wechatFriends/addFriend
+     */
+    addFriend(params: {
+        wechatAccountId: string;
+        v1: string;
+        verifyMessage?: string;
+        scene?: number;
+    }): Promise<{
+        success: boolean;
+        taskId?: string;
+    }>;
+    /**
+     * Accept friend request
+     * POST /wp/api/v1/wechatFriends/{wechatFriendId}/acceptFriend
+     */
+    acceptFriend(wechatFriendId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Update friend remark
+     * PUT /wp/api/v1/wechatFriends/{wechatFriendId}/remark
+     */
+    updateFriendRemark(wechatFriendId: string, remark: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Update friend labels
+     * PUT /wp/api/v1/wechatFriends/{wechatFriendId}/label
+     */
+    updateFriendLabels(wechatFriendId: string, labelIds: string[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get all chatrooms for a WeChat account
+     * GET /wp/api/v1/wechatAccounts/{wechatAccountId}/chatrooms
+     */
+    getChatrooms(wechatAccountId: string): Promise<WeChatChatroom[]>;
+    /**
+     * Get chatroom info by chatroomId
+     * GET /wp/api/v1/wechatChatrooms/{wechatChatroomId}
+     */
+    getChatroom(wechatChatroomId: string): Promise<WeChatChatroom>;
+    /**
+     * Update chatroom name (announcement)
+     * PUT /wp/api/v1/wechatChatrooms/{wechatChatroomId}/chatroomName
+     */
+    updateChatroomName(wechatChatroomId: string, name: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Publish chatroom announcement
+     * PUT /api/v1/wechat/chatroom/announcement
+     */
+    publishChatroomAnnouncement(wechatChatroomId: string, content: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get friend messages (1-on-1 chat)
+     * GET /wp/api/v1/wechat/friendMessages
+     */
+    getFriendMessages(params: {
+        wechatAccountId: string;
+        friendWechatId: string;
+        startTime?: number;
+        endTime?: number;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        list: WeChatMessage[];
+        total: number;
+    }>;
+    /**
+     * Get chatroom messages (group chat)
+     * GET /wp/api/v1/wechat/chatroomMessages
+     */
+    getChatroomMessages(params: {
+        wechatAccountId: string;
+        chatroomId: string;
+        startTime?: number;
+        endTime?: number;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        list: WeChatMessage[];
+        total: number;
+    }>;
+    /**
+     * Send friend message (1-on-1)
+     * POST /wp/api/v1/wechat/friendMessages
+     */
+    sendFriendMessage(params: {
+        wechatAccountId: string;
+        friendWechatId: string;
+        content: string;
+        type?: 'text' | 'image' | 'video' | 'file' | 'link';
+    }): Promise<SendMessageResult>;
+    /**
+     * Send chatroom message (group)
+     * POST /wp/api/v1/wechat/chatroomMessages
+     */
+    sendChatroomMessage(params: {
+        wechatAccountId: string;
+        chatroomId: string;
+        content: string;
+        type?: 'text' | 'image' | 'video' | 'file' | 'link';
+        atUsers?: string[];
+    }): Promise<SendMessageResult>;
+    /**
+     * Get moments
+     * GET /wp/api/v1/moments
+     */
+    getMoments(params: {
+        wechatAccountId: string;
+        startTime?: number;
+        endTime?: number;
+        limit?: number;
+    }): Promise<{
+        list: any[];
+        total: number;
+    }>;
+    /**
+     * Publish moment (post to Moments)
+     * POST /wp/api/v1/moments
+     */
+    publishMoment(params: {
+        wechatAccountId: string;
+        content: string;
+        images?: string[];
+        videos?: string[];
+        location?: {
+            lat: number;
+            lng: number;
+            name: string;
+        };
+    }): Promise<{
+        momentId: string;
+        success: boolean;
+    }>;
+    /**
+     * Comment on a moment
+     * POST /wp/api/v1/moments/{momentId}/comment
+     */
+    commentMoment(momentId: string, content: string, replyCommentId?: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Like a moment
+     * POST /wp/api/v1/moments/{momentId}/like
+     */
+    likeMoment(momentId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Download friend message file
+     */
+    downloadFriendFile(messageId: string, wechatTime: number): Promise<Blob>;
+    /**
+     * Download chatroom message file
+     */
+    downloadChatroomFile(messageId: string, wechatTime: number): Promise<Blob>;
+    /**
+     * Parse webhook payload from WorkPhone callback
+     * This should be called by your webhook endpoint handler
+     */
+    parseWebhookPayload(payload: any): WebhookPayload | null;
+}
+/**
+ * Factory function to create a WorkPhone client from OpenClaw config
+ */
+export declare function createWorkPhoneClient(config: {
+    baseUrl: string;
+    apiKey: string;
+    accountId?: string;
+    wechatAccountId?: string;
+}): WorkPhoneWeChatClient;