@nextclaw/channel-plugin-feishu 0.2.15 → 0.2.17

package/index.ts

@@ -1,12 +1,17 @@
 import type { OpenClawPluginApi } from "./src/nextclaw-sdk/feishu.js";
+import { registerFeishuCalendarTools } from "./src/calendar.js";
 import { emptyPluginConfigSchema } from "./src/nextclaw-sdk/feishu.js";
 import { registerFeishuBitableTools } from "./src/bitable.js";
 import { feishuPlugin } from "./src/channel.js";
 import { registerFeishuChatTools } from "./src/chat.js";
 import { registerFeishuDocTools } from "./src/docx.js";
 import { registerFeishuDriveTools } from "./src/drive.js";
+import { registerFeishuIdentityTools } from "./src/identity.js";
+import { registerFeishuOAuthTool } from "./src/oauth.js";
 import { registerFeishuPermTools } from "./src/perm.js";
 import { setFeishuRuntime } from "./src/runtime.js";
+import { registerFeishuSheetsTools } from "./src/sheets.js";
+import { registerFeishuTaskTools } from "./src/task.js";
 import { registerFeishuWikiTools } from "./src/wiki.js";
 
 export { monitorFeishuProvider } from "./src/monitor.js";
@@ -59,6 +64,11 @@ const plugin = {
     registerFeishuDriveTools(api);
     registerFeishuPermTools(api);
     registerFeishuBitableTools(api);
+    registerFeishuCalendarTools(api);
+    registerFeishuTaskTools(api);
+    registerFeishuSheetsTools(api);
+    registerFeishuIdentityTools(api);
+    registerFeishuOAuthTool(api);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/channel-plugin-feishu",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "private": false,
   "description": "NextClaw Feishu/Lark channel plugin with doc/wiki/drive tools.",
   "type": "module",

package/src/accounts.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  listFeishuAccountIds,
   resolveDefaultFeishuAccountId,
   resolveDefaultFeishuAccountSelection,
   resolveFeishuAccount,
@@ -56,6 +57,15 @@ function expectUnresolvedEnvSecretRefError(key: string) {
 }
 
 describe("resolveDefaultFeishuAccountId", () => {
+  it("falls back safely when channel config is missing", () => {
+    expect(listFeishuAccountIds(undefined)).toEqual(["default"]);
+    expect(resolveDefaultFeishuAccountId(undefined)).toBe("default");
+    expect(resolveDefaultFeishuAccountSelection(undefined)).toEqual({
+      accountId: "default",
+      source: "mapped-default",
+    });
+  });
+
   it("prefers channels.feishu.defaultAccount when configured", () => {
     const cfg = {
       channels: {

package/src/accounts.ts

@@ -12,8 +12,8 @@ import type {
 /**
  * List all configured account IDs from the accounts field.
  */
-function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
-  const accounts = (cfg.channels?.feishu as FeishuConfig)?.accounts;
+function listConfiguredAccountIds(cfg?: ClawdbotConfig): string[] {
+  const accounts = (cfg?.channels?.feishu as FeishuConfig | undefined)?.accounts;
   if (!accounts || typeof accounts !== "object") {
     return [];
   }
@@ -24,7 +24,7 @@ function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
  * List all Feishu account IDs.
  * If no accounts are configured, returns [DEFAULT_ACCOUNT_ID] for backward compatibility.
  */
-export function listFeishuAccountIds(cfg: ClawdbotConfig): string[] {
+export function listFeishuAccountIds(cfg?: ClawdbotConfig): string[] {
   const ids = listConfiguredAccountIds(cfg);
   if (ids.length === 0) {
     // Backward compatibility: no accounts configured, use default
@@ -36,11 +36,11 @@ export function listFeishuAccountIds(cfg: ClawdbotConfig): string[] {
 /**
  * Resolve the default account selection and its source.
  */
-export function resolveDefaultFeishuAccountSelection(cfg: ClawdbotConfig): {
+export function resolveDefaultFeishuAccountSelection(cfg?: ClawdbotConfig): {
   accountId: string;
   source: FeishuDefaultAccountSelectionSource;
 } {
-  const preferredRaw = (cfg.channels?.feishu as FeishuConfig | undefined)?.defaultAccount?.trim();
+  const preferredRaw = (cfg?.channels?.feishu as FeishuConfig | undefined)?.defaultAccount?.trim();
   const preferred = preferredRaw ? normalizeAccountId(preferredRaw) : undefined;
   if (preferred) {
     return {
@@ -64,7 +64,7 @@ export function resolveDefaultFeishuAccountSelection(cfg: ClawdbotConfig): {
 /**
  * Resolve the default account ID.
  */
-export function resolveDefaultFeishuAccountId(cfg: ClawdbotConfig): string {
+export function resolveDefaultFeishuAccountId(cfg?: ClawdbotConfig): string {
   return resolveDefaultFeishuAccountSelection(cfg).accountId;
 }
 
@@ -72,10 +72,10 @@ export function resolveDefaultFeishuAccountId(cfg: ClawdbotConfig): string {
  * Get the raw account-specific config.
  */
 function resolveAccountConfig(
-  cfg: ClawdbotConfig,
+  cfg: ClawdbotConfig | undefined,
   accountId: string,
 ): FeishuAccountConfig | undefined {
-  const accounts = (cfg.channels?.feishu as FeishuConfig)?.accounts;
+  const accounts = (cfg?.channels?.feishu as FeishuConfig | undefined)?.accounts;
   if (!accounts || typeof accounts !== "object") {
     return undefined;
   }
@@ -86,8 +86,8 @@ function resolveAccountConfig(
  * Merge top-level config with account-specific config.
  * Account-specific fields override top-level fields.
  */
-function mergeFeishuAccountConfig(cfg: ClawdbotConfig, accountId: string): FeishuConfig {
-  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+function mergeFeishuAccountConfig(cfg: ClawdbotConfig | undefined, accountId: string): FeishuConfig {
+  const feishuCfg = cfg?.channels?.feishu as FeishuConfig | undefined;
 
   // Extract base config (exclude accounts field to avoid recursion)
   const { accounts: _ignored, defaultAccount: _ignoredDefaultAccount, ...base } = feishuCfg ?? {};

package/src/app-scope-checker.ts

@@ -0,0 +1,75 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { AppScopeCheckFailedError } from "./auth-errors.js";
+
+type CacheEntry = {
+  rawScopes: Array<{ scope: string; token_types?: string[] }>;
+  fetchedAt: number;
+};
+
+const cache = new Map<string, CacheEntry>();
+const CACHE_TTL_MS = 30 * 1000;
+
+export function invalidateAppScopeCache(appId: string): void {
+  cache.delete(appId);
+}
+
+export async function getAppGrantedScopes(
+  sdk: Lark.Client,
+  appId: string,
+  tokenType?: "user" | "tenant",
+): Promise<string[]> {
+  const cached = cache.get(appId);
+  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+    return cached.rawScopes
+      .filter((scope) => !tokenType || !scope.token_types || scope.token_types.includes(tokenType))
+      .map((scope) => scope.scope);
+  }
+
+  try {
+    const response = await (sdk as unknown as {
+      request: (params: {
+        method: string;
+        url: string;
+        params: Record<string, string>;
+      }) => Promise<{ code?: number; data?: { app?: { scopes?: Array<{ scope?: string; token_types?: string[] }> } } }>;
+    }).request({
+      method: "GET",
+      url: `/open-apis/application/v6/applications/${appId}`,
+      params: { lang: "zh_cn" },
+    });
+
+    if (response.code !== 0) {
+      throw new AppScopeCheckFailedError(appId);
+    }
+
+    const rawScopes =
+      response.data?.app?.scopes
+        ?.filter((scope): scope is { scope: string; token_types?: string[] } =>
+          typeof scope.scope === "string" && scope.scope.length > 0,
+        ) ?? [];
+    cache.set(appId, { rawScopes, fetchedAt: Date.now() });
+
+    return rawScopes
+      .filter((scope) => !tokenType || !scope.token_types || scope.token_types.includes(tokenType))
+      .map((scope) => scope.scope);
+  } catch (error) {
+    if (error instanceof AppScopeCheckFailedError) {
+      throw error;
+    }
+
+    const statusCode =
+      (error as { response?: { status?: number }; status?: number; statusCode?: number }).response
+        ?.status ??
+      (error as { status?: number }).status ??
+      (error as { statusCode?: number }).statusCode;
+    if (statusCode === 400 || statusCode === 403) {
+      throw new AppScopeCheckFailedError(appId);
+    }
+    return [];
+  }
+}
+
+export function missingScopes(appGranted: string[], apiRequired: string[]): string[] {
+  const granted = new Set(appGranted);
+  return apiRequired.filter((scope) => !granted.has(scope));
+}

package/src/auth-errors.ts

@@ -0,0 +1,90 @@
+export const LARK_ERROR = {
+  APP_SCOPE_MISSING: 99991672,
+  USER_SCOPE_INSUFFICIENT: 99991679,
+  TOKEN_INVALID: 99991668,
+  TOKEN_EXPIRED: 99991677,
+  REFRESH_TOKEN_INVALID: 20026,
+  REFRESH_TOKEN_EXPIRED: 20037,
+  REFRESH_TOKEN_REVOKED: 20064,
+  REFRESH_TOKEN_ALREADY_USED: 20073,
+  REFRESH_SERVER_ERROR: 20050,
+} as const;
+
+export const REFRESH_TOKEN_RETRYABLE = new Set<number>([LARK_ERROR.REFRESH_SERVER_ERROR]);
+export const TOKEN_RETRY_CODES = new Set<number>([
+  LARK_ERROR.TOKEN_INVALID,
+  LARK_ERROR.TOKEN_EXPIRED,
+]);
+
+export type ScopeErrorInfo = {
+  apiName: string;
+  scopes: string[];
+  appScopeVerified?: boolean;
+  appId?: string;
+};
+
+export class NeedAuthorizationError extends Error {
+  readonly userOpenId: string;
+
+  constructor(userOpenId: string) {
+    super("need_user_authorization");
+    this.name = "NeedAuthorizationError";
+    this.userOpenId = userOpenId;
+  }
+}
+
+export class AppScopeCheckFailedError extends Error {
+  readonly appId?: string;
+
+  constructor(appId?: string) {
+    super("应用缺少 application:application:self_manage 权限，无法查询应用权限配置。");
+    this.name = "AppScopeCheckFailedError";
+    this.appId = appId;
+  }
+}
+
+export class AppScopeMissingError extends Error {
+  readonly apiName: string;
+  readonly missingScopes: string[];
+  readonly appId?: string;
+
+  constructor(info: ScopeErrorInfo) {
+    super(`应用缺少权限 [${info.scopes.join(", ")}]，请管理员在飞书开放平台开通。`);
+    this.name = "AppScopeMissingError";
+    this.apiName = info.apiName;
+    this.missingScopes = info.scopes;
+    this.appId = info.appId;
+  }
+}
+
+export class UserAuthRequiredError extends Error {
+  readonly userOpenId: string;
+  readonly apiName: string;
+  readonly requiredScopes: string[];
+  readonly appScopeVerified: boolean;
+  readonly appId?: string;
+
+  constructor(userOpenId: string, info: ScopeErrorInfo) {
+    super("need_user_authorization");
+    this.name = "UserAuthRequiredError";
+    this.userOpenId = userOpenId;
+    this.apiName = info.apiName;
+    this.requiredScopes = info.scopes;
+    this.appScopeVerified = info.appScopeVerified ?? true;
+    this.appId = info.appId;
+  }
+}
+
+export class UserScopeInsufficientError extends Error {
+  readonly userOpenId: string;
+  readonly apiName: string;
+  readonly missingScopes: string[];
+
+  constructor(userOpenId: string, info: ScopeErrorInfo) {
+    super("user_scope_insufficient");
+    this.name = "UserScopeInsufficientError";
+    this.userOpenId = userOpenId;
+    this.apiName = info.apiName;
+    this.missingScopes = info.scopes;
+  }
+}

package/src/calendar-calendar.ts

@@ -0,0 +1,72 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { assertLarkOk, createToolContext, handleInvokeError, json, registerTool } from "./user-tool-helpers.js";
+
+const CalendarCalendarSchema = Type.Union([
+  Type.Object({ action: Type.Literal("list"), page_size: Type.Optional(Type.Number()), page_token: Type.Optional(Type.String()) }),
+  Type.Object({ action: Type.Literal("get"), calendar_id: Type.String() }),
+  Type.Object({ action: Type.Literal("primary") }),
+]);
+
+export function registerFeishuCalendarCalendarTool(api: OpenClawPluginApi) {
+  const { toolClient } = createToolContext(api, "feishu_calendar_calendar");
+  registerTool(
+    api,
+    {
+      name: "feishu_calendar_calendar",
+      label: "Feishu Calendar",
+      description: "按本人身份查询飞书日历列表、主日历和指定日历详情。",
+      parameters: CalendarCalendarSchema,
+      async execute(_toolCallId, params) {
+        const payload = params as {
+          action: "list" | "get" | "primary";
+          page_size?: number;
+          page_token?: string;
+          calendar_id?: string;
+        };
+        try {
+          const client = toolClient();
+          if (payload.action === "list") {
+            const response = await client.invoke(
+              "feishu_calendar_calendar.list",
+              (sdk, opts) =>
+                sdk.calendar.calendar.list(
+                  { params: { page_size: payload.page_size, page_token: payload.page_token } },
+                  opts,
+                ),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            return json({
+              calendars: (response.data as { calendar_list?: unknown[] } | undefined)?.calendar_list ?? [],
+              has_more: (response.data as { has_more?: boolean } | undefined)?.has_more ?? false,
+              page_token: (response.data as { page_token?: string } | undefined)?.page_token,
+            });
+          }
+          if (payload.action === "primary") {
+            const response = await client.invoke(
+              "feishu_calendar_calendar.primary",
+              (sdk, opts) => sdk.calendar.calendar.primary({}, opts),
+              { as: "user" },
+            );
+            assertLarkOk(response);
+            return json({
+              calendars: (response.data as { calendars?: unknown[] } | undefined)?.calendars ?? [],
+            });
+          }
+          const response = await client.invoke(
+            "feishu_calendar_calendar.get",
+            (sdk, opts) =>
+              sdk.calendar.calendar.get({ path: { calendar_id: payload.calendar_id! } }, opts),
+            { as: "user" },
+          );
+          assertLarkOk(response);
+          return json({ calendar: (response.data as { calendar?: unknown } | undefined)?.calendar ?? response.data });
+        } catch (error) {
+          return handleInvokeError(error, api);
+        }
+      },
+    },
+    { name: "feishu_calendar_calendar" },
+  );
+}

package/src/calendar-event-attendee.ts

@@ -0,0 +1,96 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
+import { assertLarkOk, createToolContext, handleInvokeError, json, registerTool, StringEnum } from "./user-tool-helpers.js";
+
+const CalendarAttendeeSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("create"),
+    calendar_id: Type.String(),
+    event_id: Type.String(),
+    attendees: Type.Array(Type.Object({ type: StringEnum(["user", "chat", "resource", "third_party"]), attendee_id: Type.String() })),
+    need_notification: Type.Optional(Type.Boolean()),
+  }),
+  Type.Object({
+    action: Type.Literal("list"),
+    calendar_id: Type.String(),
+    event_id: Type.String(),
+    page_size: Type.Optional(Type.Number()),
+    page_token: Type.Optional(Type.String()),
+    user_id_type: Type.Optional(StringEnum(["open_id", "union_id", "user_id"])),
+  }),
+]);
+
+export function registerFeishuCalendarEventAttendeeTool(api: OpenClawPluginApi) {
+  const { toolClient } = createToolContext(api, "feishu_calendar_event_attendee");
+  registerTool(api, {
+    name: "feishu_calendar_event_attendee",
+    label: "Feishu Calendar Event Attendee",
+    description: "按本人身份添加日程参会人或查看参会人列表。",
+    parameters: CalendarAttendeeSchema,
+    async execute(_toolCallId, params) {
+      const payload = params as {
+        action: "create" | "list";
+        calendar_id: string;
+        event_id: string;
+        attendees?: Array<{ type: "user" | "chat" | "resource" | "third_party"; attendee_id: string }>;
+        need_notification?: boolean;
+        page_size?: number;
+        page_token?: string;
+        user_id_type?: "open_id" | "union_id" | "user_id";
+      };
+      try {
+        const client = toolClient();
+        if (payload.action === "create") {
+          const attendeePayload = (payload.attendees ?? []).map((attendee) => {
+            if (attendee.type === "user") return { type: attendee.type, user_id: attendee.attendee_id };
+            if (attendee.type === "chat") return { type: attendee.type, chat_id: attendee.attendee_id };
+            if (attendee.type === "resource") return { type: attendee.type, room_id: attendee.attendee_id };
+            return { type: attendee.type, third_party_email: attendee.attendee_id };
+          });
+          const response = await client.invoke(
+            "feishu_calendar_event_attendee.create",
+            (sdk, opts) =>
+              sdk.calendar.calendarEventAttendee.create(
+                {
+                  path: { calendar_id: payload.calendar_id, event_id: payload.event_id },
+                  params: { user_id_type: "open_id" as never },
+                  data: {
+                    attendees: attendeePayload,
+                    need_notification: payload.need_notification ?? true,
+                  },
+                },
+                opts,
+              ),
+            { as: "user" },
+          );
+          assertLarkOk(response);
+          return json({ attendees: (response.data as { attendees?: unknown[] } | undefined)?.attendees ?? [] });
+        }
+        const response = await client.invoke(
+          "feishu_calendar_event_attendee.list",
+          (sdk, opts) =>
+            sdk.calendar.calendarEventAttendee.list(
+              {
+                path: { calendar_id: payload.calendar_id, event_id: payload.event_id },
+                params: {
+                  page_size: payload.page_size,
+                  page_token: payload.page_token,
+                  user_id_type: payload.user_id_type ?? "open_id",
+                },
+              },
+              opts,
+            ),
+          { as: "user" },
+        );
+        assertLarkOk(response);
+        return json({
+          attendees: (response.data as { items?: unknown[] } | undefined)?.items ?? [],
+          has_more: (response.data as { has_more?: boolean } | undefined)?.has_more ?? false,
+          page_token: (response.data as { page_token?: string } | undefined)?.page_token,
+        });
+      } catch (error) {
+        return handleInvokeError(error, api);
+      }
+    },
+  }, { name: "feishu_calendar_event_attendee" });
+}