@shenhh/popo-native 0.1.0

package/index.ts

@@ -0,0 +1,53 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { popoNativePlugin } from "./src/channel.js";
+import { setPopoNativeRuntime } from "./src/runtime.js";
+
+export { monitorPopoNativeProvider } from "./src/monitor.js";
+export {
+  sendMessagePopoNative,
+  sendCardPopoNative,
+  createStreamCardPopoNative,
+  updateStreamCardPopoNative,
+  updateInstructionVariableOptions,
+} from "./src/send.js";
+export {
+  uploadImagePopoNative,
+  sendImagePopoNative,
+  sendFilePopoNative,
+  sendMediaPopoNative,
+  recallMessagePopoNative,
+  getMessageReadAckPopoNative,
+  configureCardCallbackPopoNative,
+  downloadMessageFilePopoNative,
+  registerFileUploadPopoNative,
+} from "./src/media.js";
+export { probePopoNative } from "./src/probe.js";
+export { popoNativePlugin } from "./src/channel.js";
+export {
+  createTeam,
+  inviteToTeam,
+  dropTeam,
+  getTeamMembers,
+  getTeamInfo,
+  updateTeamInfo,
+  updateTeamManagement,
+} from "./src/team.js";
+export {
+  configureSubscription,
+  removeSubscription,
+  listSubscriptions,
+} from "./src/subscription.js";
+
+const plugin = {
+  id: "popo-native",
+  name: "POPO Native",
+  description: "POPO Native API channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setPopoNativeRuntime(api.runtime);
+    api.registerChannel({ plugin: popoNativePlugin });
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@shenhh/popo-native",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw POPO Native API channel plugin",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "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-popo-native.git"
+  },
+  "keywords": [
+    "openclaw",
+    "popo",
+    "netease",
+    "chatbot",
+    "ai",
+    "claude",
+    "native-api"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "popo-native",
+      "label": "POPO Native",
+      "selectionLabel": "POPO Native (网易)",
+      "docsPath": "/channels/popo-native",
+      "docsLabel": "popo-native",
+      "blurb": "POPO enterprise messaging via Native API.",
+      "aliases": [],
+      "order": 81
+    },
+    "install": {
+      "npmSpec": "@shenhh/clawdbot-popo-native",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "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/src/accounts.ts

@@ -0,0 +1,52 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { PopoNativeConfig, ResolvedPopoNativeAccount } from "./types.js";
+
+export function resolvePopoNativeCredentials(cfg?: PopoNativeConfig): {
+  appId: string;
+  appSecret: string;
+  token?: string;
+  aesKey?: string;
+  server: string;
+} | null {
+  const appId = cfg?.appId?.trim();
+  const appSecret = cfg?.appSecret?.trim();
+  if (!appId || !appSecret) return null;
+  return {
+    appId,
+    appSecret,
+    token: cfg?.token?.trim() || undefined,
+    aesKey: cfg?.aesKey?.trim() || undefined,
+    server: cfg?.server ?? "https://open.popo.netease.com",
+  };
+}
+
+export function resolvePopoNativeAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedPopoNativeAccount {
+  const popoCfg = params.cfg.channels?.["popo-native"] as PopoNativeConfig | undefined;
+  const enabled = popoCfg?.enabled !== false;
+  const creds = resolvePopoNativeCredentials(popoCfg);
+
+  return {
+    accountId: params.accountId?.trim() || DEFAULT_ACCOUNT_ID,
+    enabled,
+    configured: Boolean(creds),
+    appId: creds?.appId,
+  };
+}
+
+export function listPopoNativeAccountIds(_cfg: ClawdbotConfig): string[] {
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultPopoNativeAccountId(_cfg: ClawdbotConfig): string {
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function listEnabledPopoNativeAccounts(cfg: ClawdbotConfig): ResolvedPopoNativeAccount[] {
+  return listPopoNativeAccountIds(cfg)
+    .map((accountId) => resolvePopoNativeAccount({ cfg, accountId }))
+    .filter((account) => account.enabled && account.configured);
+}

package/src/auth.ts

@@ -0,0 +1,86 @@
+import type { PopoNativeConfig, PopoNativeToken } from "./types.js";
+import { resolvePopoNativeCredentials } from "./accounts.js";
+
+// Token cache
+let cachedToken: PopoNativeToken | null = null;
+let cachedAppId: string | null = null;
+
+/**
+ * Get a valid access token, fetching a new one if necessary.
+ * Native API has 24h expiry and no refresh token.
+ */
+export async function getAccessToken(cfg: PopoNativeConfig): Promise<string> {
+  const creds = resolvePopoNativeCredentials(cfg);
+  if (!creds) {
+    throw new Error("POPO Native credentials not configured (appId, appSecret required)");
+  }
+
+  const now = Date.now();
+
+  // Check if we have a valid cached token (with 1 minute buffer)
+  if (
+    cachedToken &&
+    cachedAppId === creds.appId &&
+    cachedToken.accessExpiredAt > now + 60000
+  ) {
+    return cachedToken.openAccessToken;
+  }
+
+  // Get a new token
+  cachedToken = await fetchNewToken(cfg);
+  cachedAppId = creds.appId;
+  return cachedToken.openAccessToken;
+}
+
+/**
+ * Fetch a new token using appId and appSecret.
+ * Native API: POST /open-apis/token
+ * Response: { openAccessToken, accessExpiredAt }
+ */
+async function fetchNewToken(cfg: PopoNativeConfig): Promise<PopoNativeToken> {
+  const creds = resolvePopoNativeCredentials(cfg);
+  if (!creds) {
+    throw new Error("POPO Native credentials not configured");
+  }
+
+  const response = await fetch(`${creds.server}/open-apis/token`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      appId: creds.appId,
+      appSecret: creds.appSecret,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`POPO Native token request failed: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as {
+    errcode?: number;
+    errmsg?: string;
+    data?: {
+      openAccessToken: string;
+      accessExpiredAt: number;
+    };
+  };
+
+  if (data.errcode !== 0 || !data.data) {
+    throw new Error(`POPO Native token request failed: ${data.errmsg || "unknown error"}`);
+  }
+
+  return {
+    openAccessToken: data.data.openAccessToken,
+    accessExpiredAt: data.data.accessExpiredAt,
+  };
+}
+
+/**
+ * Clear the token cache.
+ */
+export function clearTokenCache() {
+  cachedToken = null;
+  cachedAppId = null;
+}

package/src/bot.ts

@@ -0,0 +1,363 @@
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk";
+import {
+  buildPendingHistoryContextFromMap,
+  recordPendingHistoryEntryIfEnabled,
+  clearHistoryEntriesIfEnabled,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+  type HistoryEntry,
+} from "openclaw/plugin-sdk";
+import type { PopoNativeConfig, PopoNativeMediaInfo } from "./types.js";
+import { getPopoNativeRuntime } from "./runtime.js";
+import {
+  resolvePopoNativeGroupConfig,
+  resolvePopoNativeReplyPolicy,
+  resolvePopoNativeAllowlistMatch,
+  isPopoNativeGroupAllowed,
+} from "./policy.js";
+import { createPopoNativeReplyDispatcher } from "./reply-dispatcher.js";
+import { downloadFilePopoNative } from "./media.js";
+import type { PopoNativeMsgSendEvent } from "./types.js";
+
+export type PopoNativeMessageEvent = PopoNativeMsgSendEvent;
+
+function parseMessageContent(notify: string, msgType?: number): string {
+  // msgType: 1=text, 142=video, 171=file, 161=merge, 211=quote
+  if (msgType === 1 || !msgType) {
+    return notify;
+  }
+  return notify;
+}
+
+/**
+ * Infer placeholder text based on message type.
+ */
+function inferPlaceholder(msgType?: number): string {
+  switch (msgType) {
+    case 2: // image
+      return "<media:image>";
+    case 171: // file
+      return "<media:document>";
+    case 142: // video
+      return "<media:video>";
+    case 3: // audio
+      return "<media:audio>";
+    default:
+      return "";
+  }
+}
+
+/**
+ * Resolve media from a POPO message, downloading and saving to disk.
+ */
+async function resolvePopoNativeMediaList(params: {
+  cfg: ClawdbotConfig;
+  event: PopoNativeMessageEvent;
+  maxBytes: number;
+  log?: (msg: string) => void;
+}): Promise<PopoNativeMediaInfo[]> {
+  const { cfg, event, maxBytes, log } = params;
+  const { msgType, fileInfo, videoInfo } = event.eventData;
+
+  // Only process media message types
+  // 2=image, 142=video, 171=file
+  const fileId = fileInfo?.fileId || videoInfo?.videoId;
+  if (!fileId || (msgType !== 2 && msgType !== 142 && msgType !== 171)) {
+    return [];
+  }
+
+  const out: PopoNativeMediaInfo[] = [];
+  const core = getPopoNativeRuntime();
+
+  try {
+    const result = await downloadFilePopoNative({
+      cfg,
+      fileId,
+    });
+
+    let contentType = result.contentType;
+    if (!contentType) {
+      contentType = await core.media.detectMime({ buffer: result.buffer });
+    }
+
+    const saved = await core.channel.media.saveMediaBuffer(
+      result.buffer,
+      contentType,
+      "inbound",
+      maxBytes
+    );
+
+    out.push({
+      path: saved.path,
+      contentType: saved.contentType,
+      placeholder: inferPlaceholder(msgType),
+    });
+
+    log?.(`popo-native: downloaded media (type=${msgType}), saved to ${saved.path}`);
+  } catch (err) {
+    log?.(`popo-native: failed to download media: ${String(err)}`);
+  }
+
+  return out;
+}
+
+/**
+ * Build media payload for inbound context.
+ */
+function buildPopoNativeMediaPayload(
+  mediaList: PopoNativeMediaInfo[]
+): {
+  MediaPath?: string;
+  MediaType?: string;
+  MediaUrl?: string;
+  MediaPaths?: string[];
+  MediaUrls?: string[];
+  MediaTypes?: string[];
+} {
+  const first = mediaList[0];
+  const mediaPaths = mediaList.map((media) => media.path);
+  const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean) as string[];
+  return {
+    MediaPath: first?.path,
+    MediaType: first?.contentType,
+    MediaUrl: first?.path,
+    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+  };
+}
+
+export function parsePopoNativeMessageEvent(event: PopoNativeMessageEvent): {
+  sessionId: string;
+  messageId: string;
+  senderId: string;
+  senderEmail: string;
+  senderName?: string;
+  chatType: "p2p" | "group";
+  content: string;
+  contentType: string;
+  fileId?: string;
+} {
+  const { eventData } = event;
+  const isGroup = eventData.sessionType === 3;
+  const content = parseMessageContent(eventData.notify, eventData.msgType);
+
+  return {
+    sessionId: eventData.sessionId,
+    messageId: eventData.uuid,
+    senderId: eventData.from,
+    senderEmail: eventData.from,
+    chatType: isGroup ? "group" : "p2p",
+    content,
+    contentType: String(eventData.msgType ?? "1"),
+    fileId: eventData.fileInfo?.fileId || eventData.videoInfo?.videoId,
+  };
+}
+
+export async function handlePopoNativeMessage(params: {
+  cfg: ClawdbotConfig;
+  event: PopoNativeMessageEvent;
+  runtime?: RuntimeEnv;
+  chatHistories?: Map<string, HistoryEntry[]>;
+}): Promise<void> {
+  const { cfg, event, runtime, chatHistories } = params;
+  const popoCfg = cfg.channels?.["popo-native"] as PopoNativeConfig | undefined;
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  const ctx = parsePopoNativeMessageEvent(event);
+  const isGroup = ctx.chatType === "group";
+
+  log(`popo-native: received message from ${ctx.senderEmail} in ${ctx.sessionId} (${ctx.chatType})`);
+
+  const historyLimit = Math.max(
+    0,
+    popoCfg?.historyLimit ?? cfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT
+  );
+
+  if (isGroup) {
+    const groupPolicy = popoCfg?.groupPolicy ?? "open";
+    const groupAllowFrom = popoCfg?.groupAllowFrom ?? [];
+    const groupConfig = resolvePopoNativeGroupConfig({ cfg: popoCfg, groupId: ctx.sessionId });
+
+    // Check if this GROUP is allowed
+    const groupAllowed = isPopoNativeGroupAllowed({
+      groupPolicy,
+      allowFrom: groupAllowFrom,
+      senderId: ctx.sessionId,
+      senderName: undefined,
+    });
+
+    if (!groupAllowed) {
+      log(`popo-native: group ${ctx.sessionId} not in allowlist`);
+      return;
+    }
+
+    // Additional sender-level allowlist check if group has specific allowFrom config
+    const senderAllowFrom = groupConfig?.allowFrom ?? [];
+    if (senderAllowFrom.length > 0) {
+      const senderAllowed = isPopoNativeGroupAllowed({
+        groupPolicy: "allowlist",
+        allowFrom: senderAllowFrom,
+        senderId: ctx.senderEmail,
+        senderName: ctx.senderName,
+      });
+      if (!senderAllowed) {
+        log(`popo-native: sender ${ctx.senderEmail} not in group ${ctx.sessionId} sender allowlist`);
+        return;
+      }
+    }
+
+    // Check @ mention requirement
+    const requireMention = groupConfig?.requireMention ?? popoCfg?.requireMention ?? true;
+    if (requireMention && event.eventData.atType !== 1 && event.eventData.atType !== 2) {
+      log(`popo-native: message not @ mentioning bot, skipping`);
+      return;
+    }
+  } else {
+    const dmPolicy = popoCfg?.dmPolicy ?? "pairing";
+    const allowFrom = popoCfg?.allowFrom ?? [];
+
+    if (dmPolicy === "allowlist") {
+      const match = resolvePopoNativeAllowlistMatch({
+        allowFrom,
+        senderId: ctx.senderEmail,
+      });
+      if (!match.allowed) {
+        log(`popo-native: sender ${ctx.senderEmail} not in DM allowlist`);
+        return;
+      }
+    }
+  }
+
+  try {
+    const core = getPopoNativeRuntime();
+
+    const popoFrom = `popo-native:${ctx.senderEmail}`;
+    const popoTo = isGroup ? `group:${ctx.sessionId}` : `user:${ctx.senderEmail}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "popo-native",
+      peer: {
+        kind: isGroup ? "group" : "dm",
+        id: ctx.sessionId,
+      },
+    });
+
+    const preview = ctx.content.replace(/\s+/g, " ").slice(0, 160);
+    const inboundLabel = isGroup
+      ? `POPO Native message in group ${ctx.sessionId}`
+      : `POPO Native DM from ${ctx.senderEmail}`;
+
+    core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
+      sessionKey: route.sessionKey,
+      contextKey: `popo-native:message:${ctx.sessionId}:${ctx.messageId}`,
+    });
+
+    // Resolve media from message
+    const mediaMaxBytes = (popoCfg?.mediaMaxMb ?? 20) * 1024 * 1024;
+    const mediaList = await resolvePopoNativeMediaList({
+      cfg,
+      event,
+      maxBytes: mediaMaxBytes,
+      log,
+    });
+    const mediaPayload = buildPopoNativeMediaPayload(mediaList);
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+
+    // Build message body
+    let messageBody = ctx.content;
+    const speaker = ctx.senderName ?? ctx.senderEmail;
+    messageBody = `${speaker}: ${messageBody}`;
+
+    // Apply global system prompt if configured
+    const systemPrompt = popoCfg?.systemPrompt?.trim();
+    if (systemPrompt) {
+      messageBody = `${systemPrompt}\n\n---\n\n${messageBody}`;
+    }
+
+    const envelopeFrom = isGroup ? `${ctx.sessionId}:${ctx.senderEmail}` : ctx.senderEmail;
+
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "POPO Native",
+      from: envelopeFrom,
+      timestamp: new Date(),
+      envelope: envelopeOptions,
+      body: messageBody,
+    });
+
+    let combinedBody = body;
+    const historyKey = isGroup ? ctx.sessionId : undefined;
+
+    if (isGroup && historyKey && chatHistories) {
+      combinedBody = buildPendingHistoryContextFromMap({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+        currentMessage: combinedBody,
+        formatEntry: (entry) =>
+          core.channel.reply.formatAgentEnvelope({
+            channel: "POPO Native",
+            from: `${ctx.sessionId}:${entry.sender}`,
+            timestamp: entry.timestamp,
+            body: entry.body,
+            envelope: envelopeOptions,
+          }),
+      });
+    }
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: combinedBody,
+      RawBody: ctx.content,
+      CommandBody: ctx.content,
+      From: popoFrom,
+      To: popoTo,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: isGroup ? "group" : "direct",
+      GroupSubject: isGroup ? ctx.sessionId : undefined,
+      SenderName: ctx.senderName ?? ctx.senderEmail,
+      SenderId: ctx.senderEmail,
+      Provider: "popo-native" as const,
+      Surface: "popo-native" as const,
+      MessageSid: ctx.messageId,
+      Timestamp: Date.now(),
+      WasMentioned: isGroup && (event.eventData.atType === 1 || event.eventData.atType === 2),
+      CommandAuthorized: true,
+      OriginatingChannel: "popo-native" as const,
+      OriginatingTo: popoTo,
+      ...mediaPayload,
+    });
+
+    const { dispatcher, replyOptions, markDispatchIdle } = createPopoNativeReplyDispatcher({
+      cfg,
+      agentId: route.agentId,
+      runtime: runtime as RuntimeEnv,
+      sessionId: ctx.sessionId,
+    });
+
+    log(`popo-native: dispatching to agent (session=${route.sessionKey})`);
+
+    const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions,
+    });
+
+    markDispatchIdle();
+
+    if (isGroup && historyKey && chatHistories) {
+      clearHistoryEntriesIfEnabled({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+      });
+    }
+
+    log(`popo-native: dispatch complete (queuedFinal=${queuedFinal}, replies=${counts.final})`);
+  } catch (err) {
+    error(`popo-native: failed to dispatch message: ${String(err)}`);
+  }
+}