@shenhh/popo 0.1.13 → 0.1.14

package/index.ts

@@ -12,9 +12,32 @@ export {
   updateStreamCardPopo,
   updateInstructionVariableOptions,
 } from "./src/send.js";
-export { uploadImagePopo, uploadFilePopo, sendImagePopo, sendFilePopo, sendMediaPopo } from "./src/media.js";
+export {
+  uploadImagePopo,
+  uploadFilePopo,
+  sendImagePopo,
+  sendFilePopo,
+  sendMediaPopo,
+  recallMessagePopo,
+  getMessageReadAckPopo,
+  configureCardCallbackPopo,
+  downloadMessageFilePopo,
+  registerFileUploadPopo,
+} from "./src/media.js";
 export { probePopo } from "./src/probe.js";
 export { popoPlugin } from "./src/channel.js";
+export {
+  createTeam,
+  inviteToTeam,
+  dropTeam,
+  getTeamMembers,
+  getTeamInfo,
+  updateTeamInfo,
+  updateTeamManagement,
+  getViewScope,
+  modifyViewScope,
+  publishRobot,
+} from "./src/team.js";
 
 const plugin = {
   id: "popo",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenhh/popo",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "description": "OpenClaw POPO channel plugin",
   "license": "MIT",

package/skills/popo-admin/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: popo-admin
+description: |
+  POPO robot administration operations. Activate when user mentions robot visibility, publishing, or admin settings.
+---
+
+# POPO Admin Tool
+
+Manage robot visibility scope and publishing.
+
+## Overview
+
+POPO admin operations support:
+- Query robot visibility scope (who can see/use the robot)
+- Modify visibility scope (add/remove users or departments)
+- Apply to publish robot changes
+
+## Actions
+
+### Get View Scope
+
+Query the current visibility scope of the robot.
+
+```json
+{
+  "action": "get_view_scope",
+  "scopeType": "PERSONAL",
+  "current": 1,
+  "limit": 10
+}
+```
+
+**Parameters:**
+- `scopeType` (optional): "PERSONAL" (default) or "DEPARTMENT"
+- `current` (optional): Current page, default 1
+- `limit` (optional): Page size, default 10
+
+**Response:**
+```json
+{
+  "success": true,
+  "records": [
+    {
+      "scopeType": "PERSONAL",
+      "scopeValue": "user@corp.netease.com"
+    },
+    {
+      "scopeType": "DEPARTMENT",
+      "scopeValue": "D001"
+    }
+  ],
+  "viewScopeType": 2,
+  "total": 2,
+  "size": 10,
+  "current": 1
+}
+```
+
+**View Scope Types:**
+- `1` - All visible (全员可见)
+- `2` - Partial visible (部分可见)
+
+### Modify View Scope
+
+Add or remove users/departments from robot visibility scope.
+
+```json
+{
+  "action": "modify_view_scope",
+  "operationType": 1,
+  "scopeType": "PERSONAL",
+  "scopeValues": ["user1@corp.netease.com", "user2@corp.netease.com"]
+}
+```
+
+**Parameters:**
+- `operationType` (required): 1=add, 2=delete
+- `scopeType` (required): "PERSONAL" or "DEPARTMENT"
+- `scopeValues` (required): Array of emails or department IDs
+
+**Response:**
+```json
+{
+  "success": true,
+  "successNum": 2,
+  "failNum": 0,
+  "failMsg": {}
+}
+```
+
+**Notes:**
+- To delete scope, the user/department must have been explicitly added before
+- Cannot modify "all visible" scope directly - must be partial visible first
+- Changes require publishing to take effect
+
+### Publish Robot
+
+Apply to publish robot visibility changes (requires admin approval).
+
+```json
+{
+  "action": "publish_robot",
+  "uid": "admin@corp.netease.com"
+}
+```
+
+**Parameters:**
+- `uid` (required): Applicant email (must be robot creator or admin)
+
+**Notes:**
+- After modifying visibility scope, you must call publish for changes to take effect
+- Publishing requires admin approval
+- New visibility scope will be merged with existing scope
+
+## Examples
+
+### Add users to visibility scope
+
+```json
+{
+  "action": "modify_view_scope",
+  "operationType": 1,
+  "scopeType": "PERSONAL",
+  "scopeValues": [
+    "pm@corp.netease.com",
+    "dev1@corp.netease.com",
+    "dev2@corp.netease.com"
+  ]
+}
+```
+
+### Add department to visibility scope
+
+```json
+{
+  "action": "modify_view_scope",
+  "operationType": 1,
+  "scopeType": "DEPARTMENT",
+  "scopeValues": ["D001", "D002"]
+}
+```
+
+### Remove user from scope
+
+```json
+{
+  "action": "modify_view_scope",
+  "operationType": 2,
+  "scopeType": "PERSONAL",
+  "scopeValues": ["former@corp.netease.com"]
+}
+```
+
+### Query current scope
+
+```json
+{
+  "action": "get_view_scope",
+  "scopeType": "PERSONAL",
+  "limit": 50
+}
+```
+
+### Publish changes
+
+```json
+{
+  "action": "publish_robot",
+  "uid": "creator@corp.netease.com"
+}
+```
+
+## Configuration
+
+```yaml
+channels:
+  popo:
+    enabled: true
+    appKey: "your_app_key"
+    appSecret: "your_app_secret"
+    token: "your_token"
+    aesKey: "your_aes_key"
+```
+
+## Important Notes
+
+- Visibility changes require admin approval via `publish_robot`
+- Cannot modify scope if robot is set to "all visible"
+- When deleting scope, the target must have been explicitly added
+- Publishing merges new scope with existing approved scope
+
+## API Reference
+
+- Get view scope: `POST /open-apis/robots/v1/view-scope`
+- Modify view scope: `POST /open-apis/robots/v1/view-scope/modify`
+- Publish robot: `POST /open-apis/robots/v1/view-scope/publish`

package/skills/popo-card/SKILL.md

@@ -451,6 +451,113 @@ Update dynamic options for slash command (/command) variables dynamically.
 | `101506` | Variable not found in instruction |
 | `101507` | Variable uses static options, cannot update |
 
+## Webhook Events
+
+POPO sends various event types to your webhook endpoint:
+
+### Card Action Event
+
+When users click buttons on cards:
+
+```json
+{
+  "eventType": "ACTION",
+  "eventData": {
+    "param": {
+      "actionType": "button_click",
+      "actionData": {
+        "buttonId": "approve_btn",
+        "action": "approve"
+      }
+    }
+  }
+}
+```
+
+### User Join Group Event
+
+```json
+{
+  "eventType": "TEAM_USER_JOIN_GROUP",
+  "eventData": {
+    "timetag": 1732179814141,
+    "uids": ["user@corp.netease.com"],
+    "type": 1,
+    "tid": "1234567",
+    "robotId": "robot123"
+  }
+}
+```
+
+### User Leave Group Event
+
+```json
+{
+  "eventType": "TEAM_USER_LEAVE_GROUP",
+  "eventData": {
+    "timetag": 1732179967704,
+    "uids": ["user@corp.netease.com"],
+    "type": 2,
+    "tid": "1234567",
+    "robotId": "robot123"
+  }
+}
+```
+
+### User Visit Robot Event
+
+When user opens conversation with robot:
+
+```json
+{
+  "eventType": "IM_USER_VISIT",
+  "eventData": {
+    "uid": "user@corp.netease.com",
+    "timetag": 1732184022650,
+    "robotId": "robot123"
+  }
+}
+```
+
+## Card Callback Configuration
+
+Configure webhook callback for card button interactions.
+
+### Configure Card Callback
+
+```json
+{
+  "action": "configure_card_callback",
+  "configKey": "notifyForTeam-01",
+  "requestUrl": "https://your-server.com/popo/card-callback",
+  "token": "your-verification-token",
+  "aesKey": "eSy7nSDKtFarNn45LYUcTBwPGt4u6PKG",
+  "overwriteUpdate": true,
+  "withCallBackTest": true,
+  "pushToOffice": false,
+  "authType": "SIGN"
+}
+```
+
+**Parameters:**
+- `configKey` (required): Unique callback key (max 64 chars)
+- `requestUrl` (required): URL to receive callbacks (max 256 chars)
+- `token` (required): Verification token for signature (max 64 chars)
+- `aesKey` (optional): 32-char AES key for encryption
+- `overwriteUpdate` (optional): Set to `true` to update existing config
+- `withCallBackTest` (optional): Test callback URL before saving (default: true)
+- `pushToOffice` (optional): Push from office network (default: false)
+- `authType` (optional): `CODE` or `SIGN` (default: SIGN)
+
+**Callback Verification:**
+
+When `withCallBackTest` is true, POPO will send a GET request to your URL:
+```
+GET https://your-server.com/popo/card-callback?nonce=xxx
+```
+
+Your server must return the nonce parameter in response to verify.
+
 ## API Reference
 
 - Send message: `POST /open-apis/robots/v1/im/send-msg` with `msgType: "card"`
@@ -458,3 +565,4 @@ Update dynamic options for slash command (/command) variables dynamically.
 - Create streaming card: `POST /open-apis/robots/v1/im/send-msg` with streaming template
 - Update streaming card: `PUT /open-apis/robots/v1/im/msg-card/stream`
 - Update instruction options: `POST /open-apis/robots/v1/instruction/variable/options`
+- Configure card callback: `POST /open-apis/robots/v1/im/msg-card/callback`

package/skills/popo-msg/SKILL.md

@@ -231,6 +231,126 @@ Common errors:
 - `4005` - Bot not in group (for group messages)
 - `4006` - Permission denied (sending to unauthorized user)
 
+## Message Operations
+
+### Recall Message
+
+Recall (retract) a sent message within the allowed time window.
+
+```json
+{
+  "action": "recall_message",
+  "msgId": "794076f2-68b1-4d0e-94eb-c15946580b56",
+  "sessionId": "user@corp.netease.com",
+  "sessionType": 1
+}
+```
+
+**Parameters:**
+- `msgId` (required): Message ID to recall
+- `sessionId` (required): Session ID (user email for P2P, group ID for group)
+- `sessionType` (required): `1` for P2P, `3` for group
+
+**Note:** Messages can only be recalled within a limited time (typically 2 minutes).
+
+### Query Message Read Status
+
+Query read/unread status for group messages.
+
+```json
+{
+  "action": "get_message_read_ack",
+  "msgId": "1000016836-0000000004",
+  "sessionType": 3,
+  "type": 1,
+  "st": 1672221224000,
+  "page": 1,
+  "size": 30
+}
+```
+
+**Parameters:**
+- `msgId` (required): Message ID
+- `sessionType` (required): Must be `3` (group)
+- `type` (required): `1` for read list, `2` for unread list
+- `st` (required): Query end timestamp (milliseconds)
+- `page` (optional): Page number, default 1
+- `size` (optional): Page size, default 30
+
+**Response:**
+```json
+{
+  "success": true,
+  "rnum": 10,
+  "unrnum": 15,
+  "ratList": ["user@corp.netease.com"],
+  "list": [
+    {
+      "uid": "user@corp.netease.com",
+      "name": "张三",
+      "avatar": "https://xxx/avatar.png"
+    }
+  ]
+}
+```
+
+### Download Message File
+
+Get download URL for a file from message.
+
+```json
+{
+  "action": "download_message_file",
+  "fileId": "a2759a44-xxxx-xxxx-xxxx-2fcbe67a286a"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "downloadUrl": "https://xxx/download?expires=..."
+}
+```
+
+**Note:** Download URL is valid for 1 hour.
+
+### Register File Upload
+
+Register file info and get upload URL for large files.
+
+```json
+{
+  "action": "register_file_upload",
+  "fileType": "mp4",
+  "fileName": "presentation.mp4",
+  "fileMd5": "e45d9335d1e027d3e64fd3b01c116886",
+  "duration": 120,
+  "height": 1080,
+  "width": 1920
+}
+```
+
+**Parameters:**
+- `fileType` (required): File extension (mp4, mp3, pdf, etc.)
+- `fileName` (required): File name
+- `fileMd5` (required): MD5 hash of file content
+- `duration` (optional): Duration in seconds (for audio/video)
+- `height` (optional): Video height
+- `width` (optional): Video width
+- `coverUrl` (optional): Video cover image URL
+
+**Response:**
+```json
+{
+  "success": true,
+  "fileKey": "490aa189-5589-4902-bad1-9281d817804d",
+  "uploadUrl": "https://open.popo.netease.com:8281/open-apis/robots/v1/im/file/.../upload"
+}
+```
+
+**Note:** After getting uploadUrl, upload file within 1 hour using POST form-data.
+
 ## Rate Limits
 
 - Text messages: 100 messages/minute per bot