zapry-openclaw-plugin 0.0.1

package/README.md

@@ -0,0 +1,127 @@
+# @zapry/openclaw-plugin
+
+OpenClaw channel plugin for [Zapry](https://zapry.io) — a social platform with messaging, groups, feed, clubs, and wallet.
+
+Install this plugin to let your OpenClaw agent interact with Zapry through `channel: "zapry"`.
+
+## Features
+
+- **Messaging** — Send text/media, delete messages, answer callback queries
+- **Receive/Webhook** — Poll updates, manage webhooks, inspect inbound endpoint
+- **Skills** — Manage SOUL, skills, and derived profile
+- **Directory & Groups** — Query chats/groups/members and perform moderation actions
+- **Agent Self** — Manage name/description/wallet/privacy and query contacts/friend requests
+- **Feed & Club** — Query/publish/engage posts and manage clubs
+
+## Install
+
+```bash
+openclaw plugins install @zapry/openclaw-plugin
+```
+
+## Development Notes
+
+- `node_modules/` is ignored by Git and should not be committed.
+- If `node_modules` was ever tracked in your local branch, untrack it with:
+
+```bash
+git rm -r --cached node_modules
+```
+
+## Configure
+
+Get a bot token from [Zapry BotMother](https://botmother-dev.mimo.immo), then add it to your config:
+
+```jsonc
+// ~/.openclaw/openclaw.json
+{
+  "channels": {
+    "zapry": {
+      "botToken": "YOUR_BOT_TOKEN"
+    }
+  }
+}
+```
+
+Multi-bot setup:
+
+```jsonc
+{
+  "channels": {
+    "zapry": {
+      "accounts": {
+        "market-bot": { "botToken": "TOKEN_A" },
+        "support-bot": { "botToken": "TOKEN_B" }
+      }
+    }
+  }
+}
+```
+
+Restart the gateway after configuring:
+
+```bash
+openclaw gateway restart
+```
+
+## Usage
+
+The plugin registers a `zapry` skill. Your agent will automatically use it when Zapry-related intents are detected.
+
+```
+You:   Post "Good morning!" to my Zapry feed
+Agent: → zapry_post { content: "Good morning!" }
+       Done, post published.
+```
+
+### Available Actions
+
+- Messaging: `send-message`, `send-photo`, `send-video`, `send-document`, `send-audio`, `send-voice`, `send-animation`, `generate-audio`, `delete-message`, `answer-callback-query`
+- Receive/Webhook: `get-updates`, `get-file`, `set-webhook`, `get-webhook-info`, `delete-webhook`, `webhooks-token`
+- Skills: `set-my-soul`, `get-my-soul`, `set-my-skills`, `get-my-skills`, `get-my-profile`
+- Group Query & Moderation: `get-my-groups`, `get-my-chats`, `get-chat-member`, `get-chat-members`, `get-chat-member-count`, `get-chat-administrators`, `mute-chat-member`, `kick-chat-member`, `set-chat-title`, `set-chat-description`
+- Agent Self Management: `get-me`, `get-user-profile-photos`, `set-my-wallet-address`, `set-my-friend-verify`, `get-my-contacts`, `get-my-friend-requests`, `set-my-name`, `set-my-description`
+- Feed: `get-trending-posts`, `get-latest-posts`, `get-my-posts`, `search-posts`, `create-post`, `delete-post`, `comment-post`, `like-post`, `share-post`
+- Club: `get-my-clubs`, `create-club`, `update-club`
+
+### Parameter Conventions (Important)
+
+This plugin follows the API reference 1:1. Prefer documented parameter names in `zapry_action` / `zapry_post` tool calls:
+
+- IDs: `chat_id`, `user_id`, `message_id`, `callback_query_id`, `file_id`, `dynamic_id`, `club_id`
+- Content: `text`, `photo`, `video`, `document`, `audio`, `voice`, `animation`, `content`
+- Paging: `page`, `page_size`
+- Bot/Privacy: `name`, `description`, `wallet_address`, `need_verify`, `pending_only`
+- Skills: `soulMd`, `skills`, `version`, `source`, `agentKey`
+
+Common camelCase aliases are still accepted (`chatId`, `userId`, `messageId`, `dynamicId`, `clubId`, `pageSize`, `languageCode`), but snake_case is canonical.
+
+Group moderation note:
+
+- `mute-chat-member` only supports `mute` boolean (`true` mute / `false` unmute).
+- Duration fields like `until_date` / `duration` are not supported by current API contract.
+
+Media source constraint (important):
+
+- For media send actions, use only `data:` URI or `/_temp/media/...` (or absolute URL ending with `/_temp/media/...`).
+- `create-post` images follow the same rule; local file paths are auto-converted to `data:` URI by this plugin.
+- Raw external file/image URLs are rejected by Zapry OpenAPI and will return `400`.
+
+Audio generation helper:
+
+- `generate-audio` is a plugin-local helper action (not OpenAPI 1:1) that does **TTS or procedural rendering** and then sends via `sendAudio`.
+- Typical params: `chat_id` (required), optional `prompt`, `audio_mode` (`auto`/`tts`/`render`), `audio_format` (`mp3`/`wav`), `duration_seconds`, `tts_voice`, `fallback_text`.
+- On generation/send failure, the plugin will best-effort send fallback text to the chat.
+
+## Configuration Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `botToken` | string | — | Bot token from BotMother (required) |
+| `apiBaseUrl` | string | `https://openapi-dev.mimo.immo` | Zapry API server URL |
+| `mode` | `"polling"` \| `"webhook"` | `"polling"` | Inbound runtime now uses polling as the single processing path; `webhook` is accepted but falls back to polling |
+| `webhookUrl` | string | — | Legacy webhook callback URL, retained only for backward-compatible config parsing |
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,345 @@
+if (typeof globalThis.DOMMatrix === "undefined") {
+  (globalThis as any).DOMMatrix = class DOMMatrix {
+    a: number; b: number; c: number; d: number; e: number; f: number;
+    m11: number; m12: number; m21: number; m22: number; m41: number; m42: number;
+    is2D = true; isIdentity = false;
+    constructor(init?: number[] | string) {
+      const v = Array.isArray(init) ? init : [];
+      this.a = this.m11 = v[0] ?? 1; this.b = this.m12 = v[1] ?? 0;
+      this.c = this.m21 = v[2] ?? 0; this.d = this.m22 = v[3] ?? 1;
+      this.e = this.m41 = v[4] ?? 0; this.f = this.m42 = v[5] ?? 0;
+    }
+    inverse() { return new DOMMatrix(); }
+    multiply() { return new DOMMatrix(); }
+    scale() { return new DOMMatrix(); }
+    translate() { return new DOMMatrix(); }
+    transformPoint(p?: any) { return { x: p?.x ?? 0, y: p?.y ?? 0, z: 0, w: 1 }; }
+    static fromMatrix() { return new DOMMatrix(); }
+    static fromFloat32Array(a: Float32Array) { return new DOMMatrix(Array.from(a)); }
+    static fromFloat64Array(a: Float64Array) { return new DOMMatrix(Array.from(a)); }
+  };
+}
+
+try {
+  const { createRequire } = require("node:module");
+  const { pathToFileURL } = require("node:url");
+  const _r = createRequire(require("node:path").join(process.cwd(), "package.json"));
+  const _pdfjsAbs = _r.resolve("pdfjs-dist/legacy/build/pdf.mjs");
+  const _workerAbs = _r.resolve("pdfjs-dist/legacy/build/pdf.worker.mjs");
+  import(pathToFileURL(_pdfjsAbs).href).then((pdfjs: any) => {
+    if (pdfjs?.GlobalWorkerOptions && !pdfjs.GlobalWorkerOptions.workerSrc) {
+      pdfjs.GlobalWorkerOptions.workerSrc = _workerAbs;
+    }
+  }).catch(() => {});
+} catch {}
+
+import { zapryPlugin } from "./src/channel.js";
+import {
+  buildZaprySkillRequestHeaders,
+  getZaprySkillInvocationContext,
+  resolveZaprySkillRequestHeaders,
+  setZapryRuntime,
+} from "./src/runtime.js";
+import { resolveZapryAccount } from "./src/config.js";
+import { handleZapryAction } from "./src/actions.js";
+
+const ZAPRY_ACTION_TOOL_ACTIONS = [
+  "send", "send-message",
+  "send-photo", "send-video", "send-document", "send-audio", "send-voice", "send-animation",
+  "generate-audio",
+  "delete-message", "answer-callback-query",
+  "get-file", "get-my-profile", "get-me",
+  "get-my-groups", "get-my-chats",
+  "get-chat-member", "get-chat-members", "get-chat-member-count", "get-chat-administrators",
+  "mute-chat-member", "kick-chat-member", "set-chat-title", "set-chat-description",
+  "get-user-profile-photos", "set-my-wallet-address", "set-my-friend-verify",
+  "get-my-contacts", "get-my-friend-requests",
+  "accept-friend-request", "reject-friend-request", "add-friend", "delete-friend",
+  "set-my-soul", "get-my-soul", "set-my-skills", "get-my-skills",
+  "set-my-name", "set-my-description",
+  "get-trending-posts", "get-latest-posts", "get-my-posts", "search-posts",
+  "delete-post", "comment-post", "like-post", "share-post",
+  "get-updates", "set-webhook", "get-webhook-info", "delete-webhook", "webhooks-token",
+  "get-chat-history",
+] as const;
+
+async function resolveRuntimeConfig(api: any): Promise<any> {
+  const runtimeConfig = api?.runtime?.config;
+  const loadConfig = runtimeConfig?.loadConfig;
+  if (typeof loadConfig === "function") {
+    try {
+      return await Promise.resolve(loadConfig());
+    } catch {
+      // fall through
+    }
+  }
+  return runtimeConfig ?? {};
+}
+
+function sameUserIdentity(left: string, right: string): boolean {
+  const normalizedLeft = left.trim();
+  const normalizedRight = right.trim();
+  if (!normalizedLeft || !normalizedRight) {
+    return false;
+  }
+  if (normalizedLeft === normalizedRight) {
+    return true;
+  }
+
+  const leftNum = Number(normalizedLeft);
+  const rightNum = Number(normalizedRight);
+  return Number.isFinite(leftNum) && Number.isFinite(rightNum) && leftNum === rightNum;
+}
+
+function resolveOwnerIdFromBotToken(botToken: string): string {
+  const trimmed = String(botToken ?? "").trim();
+  const separatorIdx = trimmed.indexOf(":");
+  if (separatorIdx <= 0) {
+    return "";
+  }
+  return trimmed.slice(0, separatorIdx).trim();
+}
+
+function resolveToolAccount(toolCtx: any, cfg: any, requestedAccountId?: string) {
+  return resolveZapryAccount(cfg, requestedAccountId ?? toolCtx?.agentAccountId);
+}
+
+function resolveToolSenderId(toolCtx: any): string {
+  return String(toolCtx?.requesterSenderId ?? "").trim();
+}
+
+function resolveToolSenderIsOwner(toolCtx: any, account: { botToken: string }): boolean {
+  if (toolCtx?.senderIsOwner === true) {
+    return true;
+  }
+  if (toolCtx?.senderIsOwner === false) {
+    return false;
+  }
+  const senderId = resolveToolSenderId(toolCtx);
+  const ownerId = resolveOwnerIdFromBotToken(account.botToken);
+  return sameUserIdentity(senderId, ownerId);
+}
+
+function shouldExposeZapryOwnerTools(toolCtx: any, account: { botToken: string }): boolean {
+  if (toolCtx?.messageChannel !== "zapry") {
+    return true;
+  }
+  const senderId = resolveToolSenderId(toolCtx);
+  if (!senderId) {
+    return false;
+  }
+  return resolveToolSenderIsOwner(toolCtx, account);
+}
+
+function resolveToolRequestHeaders(toolCtx: any): Record<string, string> {
+  const senderId = resolveToolSenderId(toolCtx);
+  if (senderId) {
+    const invocationCtx = getZaprySkillInvocationContext();
+    return buildZaprySkillRequestHeaders({
+      senderId,
+      messageSid: invocationCtx?.messageSid,
+    });
+  }
+  return resolveZaprySkillRequestHeaders();
+}
+
+function ownerDeniedToolResult(): string {
+  return JSON.stringify({
+    ok: false,
+    error: "只能是主人才可以调用",
+  });
+}
+
+const plugin = {
+  id: "zapry",
+  name: "Zapry",
+  description: "Zapry social platform channel plugin — messaging, groups, feed, clubs, and bot self-management",
+  configSchema: {
+    type: "object" as const,
+    additionalProperties: false,
+    properties: {},
+  },
+  register(api: any) {
+    setZapryRuntime(api.runtime);
+    api.registerChannel({ plugin: zapryPlugin });
+
+    api.registerTool((toolCtx: any) => {
+      const toolCfg = toolCtx?.config ?? api?.runtime?.config ?? {};
+      const account = resolveToolAccount(toolCtx, toolCfg);
+      if (!shouldExposeZapryOwnerTools(toolCtx, account)) {
+        return null;
+      }
+      return {
+        name: "zapry_post",
+        label: "Zapry Post to Feed",
+        description:
+          "Post to Zapry public feed (广场). This is the ONLY way to create a feed post. " +
+          "Pass content and optionally images. No target or routing needed.",
+        parameters: {
+          type: "object" as const,
+          properties: {
+            content: {
+              type: "string" as const,
+              description: "Post text content (required)",
+            },
+            images: {
+              type: "array" as const,
+              items: { type: "string" as const },
+              description:
+                "Array of image sources: local file paths, data: URIs, HTTP(S) URLs, or Zapry file IDs (mf_*)",
+            },
+          },
+          required: ["content"],
+        },
+        execute: async (_toolCallId: string, args: Record<string, any>) => {
+          try {
+            const cfg = await resolveRuntimeConfig(api);
+            const account = resolveToolAccount(toolCtx, cfg);
+            if (!shouldExposeZapryOwnerTools(toolCtx, account)) {
+              return ownerDeniedToolResult();
+            }
+            const result = await handleZapryAction({
+              action: "create-post",
+              channel: "zapry",
+              account,
+              params: { content: args.content, images: args.images },
+              requestHeaders: resolveToolRequestHeaders(toolCtx),
+            });
+            return JSON.stringify(result, null, 2);
+          } catch (err) {
+            return JSON.stringify({
+              ok: false,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        },
+      };
+    });
+
+    api.registerTool((toolCtx: any) => {
+      const toolCfg = toolCtx?.config ?? api?.runtime?.config ?? {};
+      const account = resolveToolAccount(toolCtx, toolCfg);
+      if (!shouldExposeZapryOwnerTools(toolCtx, account)) {
+        return null;
+      }
+      return {
+        name: "zapry_action",
+        label: "Zapry Platform Action",
+        description:
+          "Execute a Zapry platform action. Use this for: " +
+          "sending media (send-photo, send-video, send-audio, send-document, send-voice, send-animation) to any chat including groups. " +
+          "IMPORTANT: For send-photo, if user asks for an image without providing one, use 'prompt' parameter (e.g. action='send-photo', prompt='bitcoin logo') — image is auto-generated, NO photo/URL needed. " +
+          "profile queries (get-my-profile, get-me), friend operations " +
+          "(get-my-friend-requests, accept-friend-request, add-friend, etc.), " +
+          "group management (get-chat-members, mute-chat-member, kick-chat-member, etc.), " +
+          "feed reading (get-trending-posts, get-latest-posts, search-posts, etc.), " +
+          "feed interactions (delete-post, comment-post, like-post, share-post), " +
+          "bot settings (set-my-soul, set-my-skills, set-my-name, etc.), " +
+          "chat history (get-chat-history), " +
+          "and webhook/file operations (get-file, set-webhook, get-updates, etc.). " +
+          "Pass the action name and action-specific parameters as top-level fields.",
+        parameters: {
+          type: "object" as const,
+          properties: {
+            action: {
+              type: "string" as const,
+              description: "The Zapry action to execute",
+              enum: [...ZAPRY_ACTION_TOOL_ACTIONS],
+            },
+            chat_id: {
+              type: "string" as const,
+              description: "Chat/group ID (for group management actions like get-chat-members, mute-chat-member, etc.)",
+            },
+            user_id: {
+              type: "string" as const,
+              description: "User ID (for friend actions, chat member actions, etc.)",
+            },
+            file_id: {
+              type: "string" as const,
+              description: "File ID (for get-file)",
+            },
+            keyword: {
+              type: "string" as const,
+              description: "Search keyword (for search-posts)",
+            },
+            dynamic_id: {
+              type: "string" as const,
+              description: "Post/dynamic ID (for delete-post, comment-post, like-post, share-post)",
+            },
+            photo: {
+              type: "string" as const,
+              description: "Photo source: external URL (auto-downloaded), data URI, local path, or /_temp/media URL (for send-photo). If omitted but 'prompt' is provided, image will be auto-generated.",
+            },
+            prompt: {
+              type: "string" as const,
+              description: "PREFERRED for send-photo when user asks for an image: describe what to generate (e.g. 'bitcoin logo', 'cute cat'). Image is auto-generated and sent — no photo/URL needed.",
+            },
+            video: {
+              type: "string" as const,
+              description: "Video source (for send-video)",
+            },
+            document: {
+              type: "string" as const,
+              description: "Document source (for send-document)",
+            },
+            audio: {
+              type: "string" as const,
+              description: "Audio source (for send-audio)",
+            },
+            voice: {
+              type: "string" as const,
+              description: "Voice source (for send-voice)",
+            },
+            animation: {
+              type: "string" as const,
+              description: "Animation/GIF source (for send-animation)",
+            },
+            content: {
+              type: "string" as const,
+              description: "Text content (for comment-post)",
+            },
+            limit: {
+              type: "number" as const,
+              description: "Limit for results (for get-chat-history, default 50, max 50)",
+            },
+            page: {
+              type: "number" as const,
+              description: "Page number for paginated results",
+            },
+            page_size: {
+              type: "number" as const,
+              description: "Page size for paginated results",
+            },
+          },
+          required: ["action"],
+          additionalProperties: true,
+        },
+        execute: async (_toolCallId: string, args: Record<string, any>) => {
+          try {
+            const { action, channel: _ch, accountId: reqAccountId, ...params } = args ?? {};
+            const cfg = await resolveRuntimeConfig(api);
+            const account = resolveToolAccount(toolCtx, cfg, reqAccountId);
+            if (!shouldExposeZapryOwnerTools(toolCtx, account)) {
+              return ownerDeniedToolResult();
+            }
+            const result = await handleZapryAction({
+              action,
+              channel: "zapry",
+              account,
+              params,
+              requestHeaders: resolveToolRequestHeaders(toolCtx),
+            });
+            return JSON.stringify(result, null, 2);
+          } catch (err) {
+            return JSON.stringify({
+              ok: false,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        },
+      };
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

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

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "zapry-openclaw-plugin",
+  "version": "0.0.1",
+  "description": "OpenClaw Zapry channel plugin — messaging, groups, feed, clubs, and bot self-management",
+  "type": "module",
+  "license": "MIT",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "skills/",
+    "openclaw.plugin.json"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}