@shenhh/popo 0.1.8

package/index.ts

@@ -0,0 +1,23 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { popoPlugin } from "./src/channel.js";
+import { setPopoRuntime } from "./src/runtime.js";
+
+export { monitorPopoProvider } from "./src/monitor.js";
+export { sendMessagePopo, sendRichTextPopo, sendCardPopo } from "./src/send.js";
+export { uploadImagePopo, uploadFilePopo, sendImagePopo, sendFilePopo, sendMediaPopo } from "./src/media.js";
+export { probePopo } from "./src/probe.js";
+export { popoPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "popo",
+  name: "POPO",
+  description: "POPO channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setPopoRuntime(api.runtime);
+    api.registerChannel({ plugin: popoPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "popo",
+  "channels": ["popo"],
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@shenhh/popo",
+  "version": "0.1.8",
+  "type": "module",
+  "description": "OpenClaw POPO channel plugin",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "skills",
+    "openclaw.plugin.json"
+  ],
+  "author": {
+    "name": "Hengheng Shen",
+    "email": "1048157315@qq.com"
+  },
+  "publishConfig": {
+    "cache": "~/.npm",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m1heng/clawdbot-feishu.git"
+  },
+  "keywords": [
+    "openclaw",
+    "popo",
+    "netease",
+    "chatbot",
+    "ai",
+    "claude"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "popo",
+      "label": "POPO",
+      "selectionLabel": "POPO (网易)",
+      "docsPath": "/channels/popo",
+      "docsLabel": "popo",
+      "blurb": "POPO enterprise messaging.",
+      "aliases": [],
+      "order": 80
+    },
+    "install": {
+      "npmSpec": "@shenhh/clawdbot-popo-plugin",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "openclaw": "2026.1.29",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  }
+}

package/skills/popo-card/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: popo-card
+description: |
+  POPO interactive card message operations. Activate when user mentions card messages, interactive cards, or template messages.
+---
+
+# POPO Card Tool
+
+Send interactive card messages in POPO.
+
+## Overview
+
+POPO cards are interactive message templates that support:
+- Structured layouts
+- Variables for dynamic content
+- Interactive buttons and actions
+- Rich formatting
+
+## Actions
+
+### Send Card
+
+```json
+{
+  "action": "send",
+  "to": "user@example.com",
+  "templateUuid": "tpl_xxx",
+  "instanceUuid": "inst_xxx",
+  "variables": {
+    "title": "Order Notification",
+    "content": "Your order has been shipped",
+    "orderId": "12345"
+  }
+}
+```
+
+To group:
+```json
+{
+  "action": "send",
+  "to": "group:123456",
+  "templateUuid": "tpl_xxx",
+  "instanceUuid": "inst_xxx",
+  "variables": {
+    "title": "Meeting Reminder",
+    "time": "2024-01-15 10:00"
+  }
+}
+```
+
+### Update Card
+
+```json
+{
+  "action": "update",
+  "cardId": "card_xxx",
+  "variables": {
+    "status": "Completed",
+    "updatedAt": "2024-01-15 15:30"
+  }
+}
+```
+
+## Card Template Structure
+
+POPO card templates are created in the POPO developer console. Key concepts:
+
+### Template UUID
+Unique identifier for the card template design, created in POPO console.
+
+### Instance UUID
+Unique identifier for each card instance. Generate a new UUID for each card sent to track updates.
+
+### Variables
+Key-value pairs that fill in the template placeholders:
+```json
+{
+  "variables": {
+    "{{title}}": "Value for title",
+    "{{body}}": "Value for body content",
+    "{{buttonText}}": "Click Me"
+  }
+}
+```
+
+## Examples
+
+### Notification Card
+
+```json
+{
+  "action": "send",
+  "to": "user@example.com",
+  "templateUuid": "notification_tpl_001",
+  "instanceUuid": "ntf_20240115_001",
+  "variables": {
+    "type": "系统通知",
+    "title": "密码即将过期",
+    "content": "您的密码将于3天后过期，请及时修改",
+    "actionUrl": "https://account.company.com/password"
+  }
+}
+```
+
+### Approval Card
+
+```json
+{
+  "action": "send",
+  "to": "approver@example.com",
+  "templateUuid": "approval_tpl_001",
+  "instanceUuid": "apr_20240115_001",
+  "variables": {
+    "applicant": "张三",
+    "type": "请假申请",
+    "duration": "2024-01-20 至 2024-01-22",
+    "reason": "个人事务"
+  }
+}
+```
+
+### Status Update
+
+After approval action:
+```json
+{
+  "action": "update",
+  "cardId": "apr_20240115_001",
+  "variables": {
+    "status": "已批准",
+    "approver": "李四",
+    "approvedAt": "2024-01-15 16:00"
+  }
+}
+```
+
+## Configuration
+
+```yaml
+channels:
+  popo:
+    appKey: "your_app_key"
+    appSecret: "your_app_secret"
+```
+
+## Notes
+
+- Card templates must be created and approved in POPO developer console first
+- `instanceUuid` should be unique per card for tracking and updates
+- Card updates only work within the card's validity period
+- Interactive button callbacks are handled via webhook events
+
+## Callback Handling
+
+When users click card buttons, POPO sends `ACTION` events to your webhook:
+
+```json
+{
+  "eventType": "ACTION",
+  "eventData": {
+    "actionId": "approve_btn",
+    "userId": "user@example.com",
+    "cardId": "apr_20240115_001",
+    "data": { "action": "approve" }
+  }
+}
+```
+
+Handle these in your bot logic to process user interactions.

package/skills/popo-group/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: popo-group
+description: |
+  POPO group management operations. Activate when user mentions POPO groups, group members, or group management.
+---
+
+# POPO Group Tool
+
+Manage POPO groups and group members.
+
+## Actions
+
+### List Groups
+
+```json
+{ "action": "list" }
+```
+
+Returns all groups the bot is a member of.
+
+### Get Group Info
+
+```json
+{ "action": "info", "groupId": "123456" }
+```
+
+Returns: group name, member count, owner, etc.
+
+### List Group Members
+
+```json
+{ "action": "members", "groupId": "123456" }
+```
+
+Returns list of members with email and role.
+
+### Create Group
+
+```json
+{ "action": "create", "name": "Project Team", "members": ["user1@example.com", "user2@example.com"] }
+```
+
+With description:
+```json
+{ "action": "create", "name": "Project Team", "description": "Project discussion group", "members": ["user1@example.com"] }
+```
+
+### Add Members
+
+```json
+{ "action": "add_member", "groupId": "123456", "members": ["newuser@example.com"] }
+```
+
+### Remove Members
+
+```json
+{ "action": "remove_member", "groupId": "123456", "members": ["user@example.com"] }
+```
+
+### Update Group Info
+
+```json
+{ "action": "update", "groupId": "123456", "name": "New Group Name" }
+```
+
+Update description:
+```json
+{ "action": "update", "groupId": "123456", "description": "Updated description" }
+```
+
+### Leave Group
+
+```json
+{ "action": "leave", "groupId": "123456" }
+```
+
+Bot leaves the group.
+
+## Examples
+
+Create a project group:
+```json
+{
+  "action": "create",
+  "name": "2024 Q1 项目组",
+  "description": "Q1季度项目讨论群",
+  "members": ["pm@company.com", "dev@company.com", "test@company.com"]
+}
+```
+
+Add new team member:
+```json
+{ "action": "add_member", "groupId": "888888", "members": ["newjoin@company.com"] }
+```
+
+## Permissions
+
+- Bot must be group admin to add/remove members
+- Only group owner can delete the group
+- Bot can only access groups it has been added to
+
+## Configuration
+
+```yaml
+channels:
+  popo:
+    appKey: "your_app_key"
+    appSecret: "your_app_secret"
+```
+
+## Notes
+
+- Group IDs are numeric strings in POPO
+- Member identifiers are email addresses
+- Creating groups requires appropriate bot permissions from POPO admin

package/skills/popo-msg/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: popo-msg
+description: |
+  POPO message sending operations. Activate when user wants to send messages via POPO to users or groups.
+---
+
+# POPO Message Tool
+
+Send messages to POPO users or groups.
+
+## Target Formats
+
+- **User (P2P)**: `user:email@example.com` or just `email@example.com`
+- **Group**: `group:123456` or just `123456` (numeric group ID)
+
+## Actions
+
+### Send Text Message
+
+```json
+{ "action": "send", "to": "user@example.com", "text": "Hello!" }
+```
+
+To group:
+```json
+{ "action": "send", "to": "group:123456", "text": "Hello everyone!" }
+```
+
+### Send with @mention
+
+```json
+{ "action": "send", "to": "group:123456", "text": "Please review", "at": ["user1@example.com", "user2@example.com"] }
+```
+
+@all in group:
+```json
+{ "action": "send", "to": "group:123456", "text": "Important announcement", "atAll": true }
+```
+
+### Send Rich Text
+
+```json
+{
+  "action": "send_rich",
+  "to": "user@example.com",
+  "content": [
+    { "tag": "text", "text": "Hello " },
+    { "tag": "a", "text": "click here", "href": "https://example.com" }
+  ]
+}
+```
+
+Supported tags:
+- `text` - Plain text
+- `a` - Hyperlink (text + href)
+- `at` - @mention (userId)
+
+### Send Image
+
+```json
+{ "action": "send_image", "to": "user@example.com", "url": "https://example.com/image.png" }
+```
+
+From local file:
+```json
+{ "action": "send_image", "to": "user@example.com", "path": "/path/to/image.png" }
+```
+
+### Send File
+
+```json
+{ "action": "send_file", "to": "user@example.com", "url": "https://example.com/document.pdf" }
+```
+
+From local file:
+```json
+{ "action": "send_file", "to": "user@example.com", "path": "/path/to/document.pdf" }
+```
+
+## Examples
+
+Simple text to user:
+```json
+{ "action": "send", "to": "alice@company.com", "text": "会议提醒：明天上午10点开项目评审会" }
+```
+
+Announcement to group with @all:
+```json
+{ "action": "send", "to": "group:888888", "text": "全员通知：系统将于今晚23:00-24:00进行维护", "atAll": true }
+```
+
+## Configuration
+
+```yaml
+channels:
+  popo:
+    appKey: "your_app_key"
+    appSecret: "your_app_secret"
+```
+
+## Notes
+
+- POPO uses email as user identifier for P2P messages
+- Group messages require the bot to be added to the group first
+- File size limit: 20MB (configurable via `mediaMaxMb`)

package/src/accounts.ts

@@ -0,0 +1,52 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { PopoConfig, ResolvedPopoAccount } from "./types.js";
+
+export function resolvePopoCredentials(cfg?: PopoConfig): {
+  appKey: string;
+  appSecret: string;
+  token?: string;
+  aesKey?: string;
+  server: string;
+} | null {
+  const appKey = cfg?.appKey?.trim();
+  const appSecret = cfg?.appSecret?.trim();
+  if (!appKey || !appSecret) return null;
+  return {
+    appKey,
+    appSecret,
+    token: cfg?.token?.trim() || undefined,
+    aesKey: cfg?.aesKey?.trim() || undefined,
+    server: cfg?.server ?? "https://open.popo.netease.com/open-apis/robots/v1",
+  };
+}
+
+export function resolvePopoAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedPopoAccount {
+  const popoCfg = params.cfg.channels?.popo as PopoConfig | undefined;
+  const enabled = popoCfg?.enabled !== false;
+  const creds = resolvePopoCredentials(popoCfg);
+
+  return {
+    accountId: params.accountId?.trim() || DEFAULT_ACCOUNT_ID,
+    enabled,
+    configured: Boolean(creds),
+    appKey: creds?.appKey,
+  };
+}
+
+export function listPopoAccountIds(_cfg: ClawdbotConfig): string[] {
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultPopoAccountId(_cfg: ClawdbotConfig): string {
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function listEnabledPopoAccounts(cfg: ClawdbotConfig): ResolvedPopoAccount[] {
+  return listPopoAccountIds(cfg)
+    .map((accountId) => resolvePopoAccount({ cfg, accountId }))
+    .filter((account) => account.enabled && account.configured);
+}

package/src/auth.ts

@@ -0,0 +1,151 @@
+import type { PopoConfig, PopoToken } from "./types.js";
+import { resolvePopoCredentials } from "./accounts.js";
+
+// Token cache
+let cachedToken: PopoToken | null = null;
+let cachedAppKey: string | null = null;
+
+/**
+ * Get a valid access token, refreshing if necessary.
+ */
+export async function getAccessToken(cfg: PopoConfig): Promise<string> {
+  const creds = resolvePopoCredentials(cfg);
+  if (!creds) {
+    throw new Error("POPO credentials not configured (appKey, appSecret required)");
+  }
+
+  const now = Date.now();
+
+  // Check if we have a valid cached token
+  if (
+    cachedToken &&
+    cachedAppKey === creds.appKey &&
+    cachedToken.accessExpiredAt > now + 60000 // 1 minute buffer
+  ) {
+    return cachedToken.accessToken;
+  }
+
+  // Check if we can use refresh token
+  if (
+    cachedToken &&
+    cachedAppKey === creds.appKey &&
+    cachedToken.refreshExpiredAt > now + 60000
+  ) {
+    try {
+      cachedToken = await refreshAccessToken(cfg, cachedToken.refreshToken);
+      return cachedToken.accessToken;
+    } catch {
+      // Fall through to get a new token
+    }
+  }
+
+  // Get a new token
+  cachedToken = await fetchNewToken(cfg);
+  cachedAppKey = creds.appKey;
+  return cachedToken.accessToken;
+}
+
+/**
+ * Fetch a new token using appKey and appSecret.
+ */
+async function fetchNewToken(cfg: PopoConfig): Promise<PopoToken> {
+  const creds = resolvePopoCredentials(cfg);
+  if (!creds) {
+    throw new Error("POPO credentials not configured");
+  }
+
+  const response = await fetch(`${creds.server}/auth/token`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      appKey: creds.appKey,
+      appSecret: creds.appSecret,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`POPO token request failed: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as {
+    code?: number;
+    message?: string;
+    result?: {
+      accessToken: string;
+      accessExpiredAt: number;
+      refreshToken: string;
+      refreshExpiredAt: number;
+    };
+  };
+
+  if (data.code !== 200 || !data.result) {
+    throw new Error(`POPO token request failed: ${data.message || "unknown error"}`);
+  }
+
+  return {
+    accessToken: data.result.accessToken,
+    accessExpiredAt: data.result.accessExpiredAt,
+    refreshToken: data.result.refreshToken,
+    refreshExpiredAt: data.result.refreshExpiredAt,
+  };
+}
+
+/**
+ * Refresh an access token using a refresh token.
+ */
+export async function refreshAccessToken(
+  cfg: PopoConfig,
+  refreshToken: string
+): Promise<PopoToken> {
+  const creds = resolvePopoCredentials(cfg);
+  if (!creds) {
+    throw new Error("POPO credentials not configured");
+  }
+
+  const response = await fetch(`${creds.server}/auth/refresh`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      appKey: creds.appKey,
+      refreshToken,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`POPO token refresh failed: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as {
+    code?: number;
+    message?: string;
+    result?: {
+      accessToken: string;
+      accessExpiredAt: number;
+      refreshToken: string;
+      refreshExpiredAt: number;
+    };
+  };
+
+  if (data.code !== 200 || !data.result) {
+    throw new Error(`POPO token refresh failed: ${data.message || "unknown error"}`);
+  }
+
+  return {
+    accessToken: data.result.accessToken,
+    accessExpiredAt: data.result.accessExpiredAt,
+    refreshToken: data.result.refreshToken,
+    refreshExpiredAt: data.result.refreshExpiredAt,
+  };
+}
+
+/**
+ * Clear the token cache.
+ */
+export function clearTokenCache() {
+  cachedToken = null;
+  cachedAppKey = null;
+}