moltbot-channel-feishu 0.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 samzong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# moltbot-channel-feishu
+
+**Turn Feishu into your AI super-gateway.** A production-grade Feishu/Lark channel plugin for [Moltbot](https://molt.bot) — the brilliant AI agent framework.
+
+## Install
+
+```bash
+# npm
+moltbot plugin install moltbot-channel-feishu
+
+# GitHub (for testing)
+moltbot plugin install github:samzong/moltbot-channel-feishu
+```
+
+## Configure
+
+Edit `~/.clawdbot/clawdbot.json`:
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "appId": "cli_xxx",
+      "appSecret": "xxx",
+      "domain": "feishu",
+      "dmPolicy": "pairing",
+      "groupPolicy": "open"
+    }
+  }
+}
+```
+
+Or use environment variables (takes precedence if config values are empty):
+
+```bash
+export FEISHU_APP_ID="cli_xxx"
+export FEISHU_APP_SECRET="xxx"
+```
+
+### Configuration Options
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable/disable the channel |
+| `appId` | string | - | Feishu App ID |
+| `appSecret` | string | - | Feishu App Secret |
+| `domain` | `"feishu"` \| `"lark"` | `"feishu"` | API domain (China / International) |
+| `dmPolicy` | `"open"` \| `"pairing"` \| `"allowlist"` | `"pairing"` | DM access policy |
+| `allowFrom` | string[] | `[]` | User IDs allowed for DM (when `dmPolicy: "allowlist"`) |
+| `groupPolicy` | `"open"` \| `"allowlist"` \| `"disabled"` | `"allowlist"` | Group chat access policy |
+| `groupAllowFrom` | string[] | `[]` | Group IDs allowed (when `groupPolicy: "allowlist"`) |
+| `requireMention` | boolean | `true` | Require @mention in groups |
+
+## Feishu App Setup
+
+1. Go to [Feishu Open Platform](https://open.feishu.cn)
+2. Create a self-built app
+3. Enable permissions: `im:message`, `im:chat`, `contact:user.base:readonly`
+4. Events → Use **Long Connection** mode
+5. Subscribe to event: `im.message.receive_v1`
+6. Get App ID and App Secret from **Credentials** page
+7. Publish the app
+
+## License
+
+[MIT](LICENSE)
+

package/clawdbot.plugin.json

@@ -0,0 +1,33 @@
+{
+    "id": "feishu",
+    "name": "Feishu",
+    "description": "Feishu/Lark channel plugin for Moltbot",
+    "version": "0.0.8",
+    "channels": [
+        "feishu"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "appId": {
+                "type": "string",
+                "description": "Feishu App ID"
+            },
+            "appSecret": {
+                "type": "string",
+                "description": "Feishu App Secret"
+            }
+        }
+    },
+    "uiHints": {
+        "appId": {
+            "label": "App ID",
+            "placeholder": "cli_xxxxxxxx"
+        },
+        "appSecret": {
+            "label": "App Secret",
+            "sensitive": true
+        }
+    }
+}

package/moltbot.plugin.json

@@ -0,0 +1,33 @@
+{
+    "id": "feishu",
+    "name": "Feishu",
+    "description": "Feishu/Lark channel plugin for Moltbot",
+    "version": "0.0.8",
+    "channels": [
+        "feishu"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "appId": {
+                "type": "string",
+                "description": "Feishu App ID"
+            },
+            "appSecret": {
+                "type": "string",
+                "description": "Feishu App Secret"
+            }
+        }
+    },
+    "uiHints": {
+        "appId": {
+            "label": "App ID",
+            "placeholder": "cli_xxxxxxxx"
+        },
+        "appSecret": {
+            "label": "App Secret",
+            "sensitive": true
+        }
+    }
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+    "name": "moltbot-channel-feishu",
+    "version": "0.0.8",
+    "type": "module",
+    "description": "Production-grade Feishu/Lark channel plugin for Clawdbot",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/samzong/moltbot-channel-feishu.git"
+    },
+    "keywords": [
+        "clawdbot",
+        "feishu",
+        "lark",
+        "plugin",
+        "channel"
+    ],
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "files": [
+        "src",
+        "moltbot.plugin.json",
+        "clawdbot.plugin.json"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "lint": "eslint src/",
+        "lint:fix": "eslint src/ --fix",
+        "format": "prettier --write src/",
+        "format:check": "prettier --check src/",
+        "typecheck": "tsc --noEmit",
+        "test": "npm run build && vitest run",
+        "test:watch": "vitest",
+        "clean": "rm -rf dist",
+        "prerelease": "npm run lint && npm run build && npm run test && node --check dist/index.js && echo '✅ All checks passed'",
+        "dev:local": "tsx scripts/local-test.ts",
+        "version": "node scripts/sync-version.js && git add moltbot.plugin.json clawdbot.plugin.json"
+    },
+    "clawdbot": {
+        "extensions": [
+            "./src/index.ts"
+        ],
+        "channel": {
+            "id": "feishu",
+            "label": "Feishu",
+            "selectionLabel": "Feishu",
+            "docsPath": "/channels/feishu",
+            "docsLabel": "feishu",
+            "blurb": "Feishu enterprise messaging.",
+            "aliases": [
+                "lark"
+            ],
+            "order": 70
+        }
+    },
+    "dependencies": {
+        "@larksuiteoapi/node-sdk": "^1.30.0",
+        "zod": "^3.23.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.39.2",
+        "@types/node": "^22.0.0",
+        "@typescript-eslint/eslint-plugin": "^8.0.0",
+        "@typescript-eslint/parser": "^8.0.0",
+        "@vitest/coverage-v8": "^2.1.9",
+        "clawdbot": "^2026.1.24",
+        "dotenv": "^17.2.3",
+        "eslint": "^9.0.0",
+        "prettier": "^3.8.1",
+        "tsx": "^4.21.0",
+        "typescript": "^5.7.0",
+        "typescript-eslint": "^8.54.0",
+        "vite-tsconfig-paths": "^6.0.5",
+        "vitest": "^2.0.0"
+    },
+    "peerDependencies": {
+        "clawdbot": ">=2026.1.24"
+    },
+    "engines": {
+        "node": ">=20.0.0"
+    }
+}

package/src/api/client.ts

@@ -0,0 +1,140 @@
+/**
+ * Feishu API client wrapper.
+ * Provides singleton access to the Lark SDK client with connection pooling.
+ */
+
+import * as Lark from "@larksuiteoapi/node-sdk";
+import type { Config, Credentials } from "../config/schema.js";
+import { resolveCredentials } from "../config/schema.js";
+import type { ProbeResult } from "../types/index.js";
+
+// ============================================================================
+// Client Cache (Singleton Pattern)
+// ============================================================================
+
+interface CachedClient {
+  client: Lark.Client;
+  credentials: Credentials;
+}
+
+let cachedClient: CachedClient | null = null;
+
+/**
+ * Resolve Lark domain enum from config.
+ */
+function resolveDomain(domain: "feishu" | "lark"): Lark.Domain {
+  return domain === "lark" ? Lark.Domain.Lark : Lark.Domain.Feishu;
+}
+
+/**
+ * Create or retrieve the Feishu API client.
+ * Uses singleton pattern with credential-based cache invalidation.
+ *
+ * @throws Error if credentials are not configured
+ */
+export function getApiClient(config: Config): Lark.Client {
+  const credentials = resolveCredentials(config);
+  if (!credentials) {
+    throw new Error("Feishu credentials not configured (appId, appSecret required)");
+  }
+
+  // Return cached client if credentials match
+  if (
+    cachedClient &&
+    cachedClient.credentials.appId === credentials.appId &&
+    cachedClient.credentials.appSecret === credentials.appSecret &&
+    cachedClient.credentials.domain === credentials.domain
+  ) {
+    return cachedClient.client;
+  }
+
+  // Create new client
+  const client = new Lark.Client({
+    appId: credentials.appId,
+    appSecret: credentials.appSecret,
+    appType: Lark.AppType.SelfBuild,
+    domain: resolveDomain(credentials.domain),
+  });
+
+  cachedClient = { client, credentials };
+  return client;
+}
+
+/**
+ * Create a WebSocket client for real-time events.
+ *
+ * @throws Error if credentials are not configured
+ */
+export function createWsClient(config: Config): Lark.WSClient {
+  const credentials = resolveCredentials(config);
+  if (!credentials) {
+    throw new Error("Feishu credentials not configured (appId, appSecret required)");
+  }
+
+  return new Lark.WSClient({
+    appId: credentials.appId,
+    appSecret: credentials.appSecret,
+    domain: resolveDomain(credentials.domain),
+    loggerLevel: Lark.LoggerLevel.info,
+  });
+}
+
+
+
+/**
+ * Clear the client cache.
+ * Useful for testing or when credentials change.
+ */
+export function clearClientCache(): void {
+  cachedClient = null;
+}
+
+/**
+ * Probe the Feishu API to verify credentials and get bot info.
+ */
+export async function probeConnection(config: Config | undefined): Promise<ProbeResult> {
+  if (!config) {
+    return { ok: false, error: "Configuration not provided" };
+  }
+
+  const credentials = resolveCredentials(config);
+  if (!credentials) {
+    return { ok: false, error: "Credentials not configured" };
+  }
+
+  try {
+    const client = getApiClient(config);
+
+    // Use bot info endpoint to verify credentials
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const response = (await (client as any).bot.botInfo()) as {
+      code?: number;
+      msg?: string;
+      bot?: {
+        app_name?: string;
+        open_id?: string;
+      };
+    };
+
+    if (response.code !== 0) {
+      return {
+        ok: false,
+        error: response.msg ?? `API error code ${response.code}`,
+        appId: credentials.appId,
+      };
+    }
+
+    return {
+      ok: true,
+      appId: credentials.appId,
+      botName: response.bot?.app_name,
+      botOpenId: response.bot?.open_id,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+      appId: credentials.appId,
+    };
+  }
+}

package/src/api/directory.ts

@@ -0,0 +1,186 @@
+/**
+ * User and group directory operations.
+ */
+
+import type { Config } from "../config/schema.js";
+import type { DirectoryUser, DirectoryGroup, ListDirectoryParams } from "../types/index.js";
+import { getApiClient } from "./client.js";
+import { resolveCredentials } from "../config/schema.js";
+import { normalizeTarget } from "./messages.js";
+
+// ============================================================================
+// Static Directory (from config)
+// ============================================================================
+
+/**
+ * List users from config allowlists.
+ * Used as fallback when API access is unavailable.
+ */
+export function listUsersFromConfig(config: Config, params: ListDirectoryParams): DirectoryUser[] {
+  const query = params.query?.trim().toLowerCase() ?? "";
+  const ids = new Set<string>();
+
+  // Collect from DM allowlist
+  for (const entry of config.allowFrom ?? []) {
+    const trimmed = String(entry).trim();
+    if (trimmed && trimmed !== "*") ids.add(trimmed);
+  }
+
+  // Collect from DM configs
+  for (const userId of Object.keys(config.dms ?? {})) {
+    const trimmed = userId.trim();
+    if (trimmed) ids.add(trimmed);
+  }
+
+  return Array.from(ids)
+    .map((raw) => normalizeTarget(raw) ?? raw)
+    .filter((id) => !query || id.toLowerCase().includes(query))
+    .slice(0, params.limit && params.limit > 0 ? params.limit : undefined)
+    .map((id) => ({ kind: "user" as const, id }));
+}
+
+/**
+ * List groups from config allowlists.
+ * Used as fallback when API access is unavailable.
+ */
+export function listGroupsFromConfig(
+  config: Config,
+  params: ListDirectoryParams
+): DirectoryGroup[] {
+  const query = params.query?.trim().toLowerCase() ?? "";
+  const ids = new Set<string>();
+
+  // Collect from group configs
+  for (const groupId of Object.keys(config.groups ?? {})) {
+    const trimmed = groupId.trim();
+    if (trimmed && trimmed !== "*") ids.add(trimmed);
+  }
+
+  // Collect from group allowlist
+  for (const entry of config.groupAllowFrom ?? []) {
+    const trimmed = String(entry).trim();
+    if (trimmed && trimmed !== "*") ids.add(trimmed);
+  }
+
+  return Array.from(ids)
+    .filter((id) => !query || id.toLowerCase().includes(query))
+    .slice(0, params.limit && params.limit > 0 ? params.limit : undefined)
+    .map((id) => ({ kind: "group" as const, id }));
+}
+
+// ============================================================================
+// Live Directory (from API)
+// ============================================================================
+
+/**
+ * List users from Feishu API.
+ * Falls back to config-based listing if API unavailable.
+ */
+export async function listUsers(
+  config: Config,
+  params: ListDirectoryParams
+): Promise<DirectoryUser[]> {
+  const credentials = resolveCredentials(config);
+  if (!credentials) {
+    return listUsersFromConfig(config, params);
+  }
+
+  try {
+    const client = getApiClient(config);
+    const limit = params.limit ?? 50;
+    const query = params.query?.trim().toLowerCase() ?? "";
+
+    const users: DirectoryUser[] = [];
+
+    // Use SDK's iterator for automatic pagination
+    const iterator = await client.contact.user.listWithIterator({
+      params: { page_size: Math.min(limit, 50) },
+    });
+
+    for await (const page of iterator) {
+      const items = page?.items;
+      if (!items) continue;
+
+      for (const user of items) {
+        if (!user.open_id) continue;
+
+        const name = user.name ?? "";
+        const matchesQuery =
+          !query || user.open_id.toLowerCase().includes(query) || name.toLowerCase().includes(query);
+
+        if (matchesQuery) {
+          users.push({
+            kind: "user",
+            id: user.open_id,
+            name: name || undefined,
+          });
+        }
+
+        if (users.length >= limit) break;
+      }
+
+      if (users.length >= limit) break;
+    }
+
+    return users;
+  } catch {
+    return listUsersFromConfig(config, params);
+  }
+}
+
+
+/**
+ * List groups from Feishu API.
+ * Falls back to config-based listing if API unavailable.
+ */
+export async function listGroups(
+  config: Config,
+  params: ListDirectoryParams
+): Promise<DirectoryGroup[]> {
+  const credentials = resolveCredentials(config);
+  if (!credentials) {
+    return listGroupsFromConfig(config, params);
+  }
+
+  try {
+    const client = getApiClient(config);
+    const limit = params.limit ?? 50;
+    const query = params.query?.trim().toLowerCase() ?? "";
+
+    const groups: DirectoryGroup[] = [];
+
+    // Use SDK's iterator for automatic pagination
+    const iterator = await client.im.chat.listWithIterator({
+      params: { page_size: Math.min(limit, 100) },
+    });
+
+    for await (const page of iterator) {
+      const items = page?.items;
+      if (!items) continue;
+
+      for (const chat of items) {
+        if (!chat.chat_id) continue;
+
+        const name = chat.name ?? "";
+        const matchesQuery =
+          !query || chat.chat_id.toLowerCase().includes(query) || name.toLowerCase().includes(query);
+
+        if (matchesQuery) {
+          groups.push({
+            kind: "group",
+            id: chat.chat_id,
+            name: name || undefined,
+          });
+        }
+
+        if (groups.length >= limit) break;
+      }
+
+      if (groups.length >= limit) break;
+    }
+
+    return groups;
+  } catch {
+    return listGroupsFromConfig(config, params);
+  }
+}