@m1heng-clawd/feishu 0.1.9 → 0.1.11

package/src/streaming-card.ts

@@ -0,0 +1,211 @@
+import type { Client } from "@larksuiteoapi/node-sdk";
+import type { FeishuDomain } from "./types.js";
+
+type Credentials = { appId: string; appSecret: string; domain?: FeishuDomain };
+type CardState = { cardId: string; messageId: string; sequence: number; currentText: string };
+
+const tokenCache = new Map<string, { token: string; expiresAt: number }>();
+
+function resolveApiBase(domain?: FeishuDomain): string {
+  if (domain === "lark") {
+    return "https://open.larksuite.com/open-apis";
+  }
+  if (domain && domain !== "feishu" && domain.startsWith("http")) {
+    return `${domain.replace(/\/+$/, "")}/open-apis`;
+  }
+  return "https://open.feishu.cn/open-apis";
+}
+
+async function getToken(creds: Credentials): Promise<string> {
+  const key = `${creds.domain ?? "feishu"}|${creds.appId}`;
+  const cached = tokenCache.get(key);
+  if (cached && cached.expiresAt > Date.now() + 60000) {
+    return cached.token;
+  }
+
+  const res = await fetch(`${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ app_id: creds.appId, app_secret: creds.appSecret }),
+  });
+  const data = (await res.json()) as {
+    code: number;
+    msg: string;
+    tenant_access_token?: string;
+    expire?: number;
+  };
+  if (data.code !== 0 || !data.tenant_access_token) {
+    throw new Error(`Token error: ${data.msg}`);
+  }
+  tokenCache.set(key, {
+    token: data.tenant_access_token,
+    expiresAt: Date.now() + (data.expire ?? 7200) * 1000,
+  });
+  return data.tenant_access_token;
+}
+
+function truncateSummary(text: string, max = 50): string {
+  if (!text) {
+    return "";
+  }
+  const clean = text.replace(/\n/g, " ").trim();
+  return clean.length <= max ? clean : clean.slice(0, max - 3) + "...";
+}
+
+export class FeishuStreamingSession {
+  private client: Client;
+  private creds: Credentials;
+  private state: CardState | null = null;
+  private queue: Promise<void> = Promise.resolve();
+  private closed = false;
+  private log?: (msg: string) => void;
+  private lastUpdateTime = 0;
+  private pendingText: string | null = null;
+  private updateThrottleMs = 100;
+
+  constructor(client: Client, creds: Credentials, log?: (msg: string) => void) {
+    this.client = client;
+    this.creds = creds;
+    this.log = log;
+  }
+
+  async start(
+    receiveId: string,
+    receiveIdType: "open_id" | "user_id" | "union_id" | "email" | "chat_id" = "chat_id",
+  ): Promise<void> {
+    if (this.state) {
+      return;
+    }
+
+    const apiBase = resolveApiBase(this.creds.domain);
+    const cardJson = {
+      schema: "2.0",
+      config: {
+        streaming_mode: true,
+        summary: { content: "[Generating...]" },
+        streaming_config: { print_frequency_ms: { default: 50 }, print_step: { default: 2 } },
+      },
+      body: {
+        elements: [{ tag: "markdown", content: "Thinking...", element_id: "content" }],
+      },
+    };
+
+    const createRes = await fetch(`${apiBase}/cardkit/v1/cards`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${await getToken(this.creds)}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ type: "card_json", data: JSON.stringify(cardJson) }),
+    });
+    const createData = (await createRes.json()) as {
+      code: number;
+      msg: string;
+      data?: { card_id: string };
+    };
+    if (createData.code !== 0 || !createData.data?.card_id) {
+      throw new Error(`Create card failed: ${createData.msg}`);
+    }
+    const cardId = createData.data.card_id;
+
+    const sendRes = await this.client.im.message.create({
+      params: { receive_id_type: receiveIdType },
+      data: {
+        receive_id: receiveId,
+        msg_type: "interactive",
+        content: JSON.stringify({ type: "card", data: { card_id: cardId } }),
+      },
+    });
+    if (sendRes.code !== 0 || !sendRes.data?.message_id) {
+      throw new Error(`Send card failed: ${sendRes.msg}`);
+    }
+
+    this.state = { cardId, messageId: sendRes.data.message_id, sequence: 1, currentText: "" };
+    this.log?.(`Started streaming: cardId=${cardId}, messageId=${sendRes.data.message_id}`);
+  }
+
+  async update(text: string): Promise<void> {
+    if (!this.state || this.closed) {
+      return;
+    }
+    const now = Date.now();
+    if (now - this.lastUpdateTime < this.updateThrottleMs) {
+      this.pendingText = text;
+      return;
+    }
+    this.pendingText = null;
+    this.lastUpdateTime = now;
+
+    this.queue = this.queue.then(async () => {
+      if (!this.state || this.closed) {
+        return;
+      }
+      this.state.currentText = text;
+      this.state.sequence += 1;
+      const apiBase = resolveApiBase(this.creds.domain);
+      await fetch(`${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`, {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          content: text,
+          sequence: this.state.sequence,
+          uuid: `s_${this.state.cardId}_${this.state.sequence}`,
+        }),
+      }).catch((e) => this.log?.(`Update failed: ${String(e)}`));
+    });
+    await this.queue;
+  }
+
+  async close(finalText?: string): Promise<void> {
+    if (!this.state || this.closed) {
+      return;
+    }
+    this.closed = true;
+    await this.queue;
+
+    const text = finalText ?? this.pendingText ?? this.state.currentText;
+    const apiBase = resolveApiBase(this.creds.domain);
+
+    if (text && text !== this.state.currentText) {
+      this.state.sequence += 1;
+      await fetch(`${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`, {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          content: text,
+          sequence: this.state.sequence,
+          uuid: `s_${this.state.cardId}_${this.state.sequence}`,
+        }),
+      }).catch(() => {});
+      this.state.currentText = text;
+    }
+
+    this.state.sequence += 1;
+    await fetch(`${apiBase}/cardkit/v1/cards/${this.state.cardId}/settings`, {
+      method: "PATCH",
+      headers: {
+        Authorization: `Bearer ${await getToken(this.creds)}`,
+        "Content-Type": "application/json; charset=utf-8",
+      },
+      body: JSON.stringify({
+        settings: JSON.stringify({
+          config: { streaming_mode: false, summary: { content: truncateSummary(text) } },
+        }),
+        sequence: this.state.sequence,
+        uuid: `c_${this.state.cardId}_${this.state.sequence}`,
+      }),
+    }).catch((e) => this.log?.(`Close failed: ${String(e)}`));
+
+    this.log?.(`Closed streaming: cardId=${this.state.cardId}`);
+  }
+
+  isActive(): boolean {
+    return this.state !== null && !this.closed;
+  }
+}

package/src/targets.ts

@@ -45,7 +45,7 @@ export function resolveReceiveIdType(id: string): "chat_id" | "open_id" | "user_
   const trimmed = id.trim();
   if (trimmed.startsWith(CHAT_ID_PREFIX)) return "chat_id";
   if (trimmed.startsWith(OPEN_ID_PREFIX)) return "open_id";
-  return "open_id";
+  return "user_id";
 }
 
 export function looksLikeFeishuId(raw: string): boolean {

package/src/task-tools/actions.ts

@@ -0,0 +1,137 @@
+import type { TaskClient } from "./common.js";
+import type {
+  CreateTaskParams,
+  GetTaskParams,
+  TaskUpdateTask,
+  UpdateTaskParams,
+} from "./schemas.js";
+import { runTaskApiCall } from "./common.js";
+
+const SUPPORTED_PATCH_FIELDS = new Set<keyof TaskUpdateTask>([
+  "summary",
+  "description",
+  "due",
+  "start",
+  "extra",
+  "completed_at",
+  "repeat_rule",
+  "mode",
+  "is_milestone",
+]);
+
+function omitUndefined<T extends Record<string, unknown>>(obj: T): T {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, value]) => value !== undefined),
+  ) as T;
+}
+
+function inferUpdateFields(task: TaskUpdateTask): string[] {
+  return Object.keys(task).filter((field) =>
+    SUPPORTED_PATCH_FIELDS.has(field as keyof TaskUpdateTask),
+  );
+}
+
+function formatTask(task: Record<string, unknown> | undefined) {
+  if (!task) return undefined;
+  return {
+    guid: task.guid,
+    task_id: task.task_id,
+    summary: task.summary,
+    description: task.description,
+    status: task.status,
+    url: task.url,
+    created_at: task.created_at,
+    updated_at: task.updated_at,
+    completed_at: task.completed_at,
+    due: task.due,
+    start: task.start,
+    is_milestone: task.is_milestone,
+    members: task.members,
+    tasklists: task.tasklists,
+  };
+}
+
+export async function createTask(client: TaskClient, params: CreateTaskParams) {
+  const res = await runTaskApiCall("task.v2.task.create", () =>
+    client.task.v2.task.create({
+      data: omitUndefined({
+        summary: params.summary,
+        description: params.description,
+        due: params.due,
+        start: params.start,
+        extra: params.extra,
+        completed_at: params.completed_at,
+        members: params.members,
+        repeat_rule: params.repeat_rule,
+        tasklists: params.tasklists,
+        mode: params.mode,
+        is_milestone: params.is_milestone,
+      }),
+      params: omitUndefined({
+        user_id_type: params.user_id_type,
+      }),
+    }),
+  );
+
+  return {
+    task: formatTask((res.data?.task ?? undefined) as Record<string, unknown> | undefined),
+  };
+}
+
+export async function deleteTask(client: TaskClient, taskGuid: string) {
+  await runTaskApiCall("task.v2.task.delete", () =>
+    client.task.v2.task.delete({
+      path: { task_guid: taskGuid },
+    }),
+  );
+
+  return {
+    success: true,
+    task_guid: taskGuid,
+  };
+}
+
+export async function getTask(client: TaskClient, params: GetTaskParams) {
+  const res = await runTaskApiCall("task.v2.task.get", () =>
+    client.task.v2.task.get({
+      path: { task_guid: params.task_guid },
+      params: omitUndefined({
+        user_id_type: params.user_id_type,
+      }),
+    }),
+  );
+
+  return {
+    task: formatTask((res.data?.task ?? undefined) as Record<string, unknown> | undefined),
+  };
+}
+
+export async function updateTask(client: TaskClient, params: UpdateTaskParams) {
+  const task = omitUndefined(params.task as Record<string, unknown>) as TaskUpdateTask;
+  const updateFields = params.update_fields?.length ? params.update_fields : inferUpdateFields(task);
+
+  if (Object.keys(task).length === 0) {
+    throw new Error("task update payload is empty");
+  }
+  if (updateFields.length === 0) {
+    throw new Error("no valid update_fields provided or inferred from task payload");
+  }
+
+  const res = await runTaskApiCall("task.v2.task.patch", () =>
+    client.task.v2.task.patch({
+      path: { task_guid: params.task_guid },
+      data: {
+        task,
+        update_fields: updateFields,
+      },
+      params: omitUndefined({
+        user_id_type: params.user_id_type,
+      }),
+    }),
+  );
+
+  return {
+    task: formatTask((res.data?.task ?? undefined) as Record<string, unknown> | undefined),
+    update_fields: updateFields,
+  };
+}

package/src/task-tools/common.ts

@@ -0,0 +1,18 @@
+import { createFeishuClient } from "../client.js";
+import {
+  errorResult,
+  json,
+  runFeishuApiCall,
+  type FeishuApiResponse,
+} from "../tools-common/feishu-api.js";
+
+export type TaskClient = ReturnType<typeof createFeishuClient>;
+
+export { json, errorResult };
+
+export async function runTaskApiCall<T extends FeishuApiResponse>(
+  context: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return runFeishuApiCall(context, fn);
+}

package/src/task-tools/register.ts

@@ -0,0 +1,101 @@
+import type { TSchema } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { hasFeishuToolEnabledForAnyAccount, withFeishuToolClient } from "../tools-common/tool-exec.js";
+import { createTask, deleteTask, getTask, updateTask } from "./actions.js";
+import { errorResult, json, type TaskClient } from "./common.js";
+import {
+  CreateTaskSchema,
+  type CreateTaskParams,
+  DeleteTaskSchema,
+  type DeleteTaskParams,
+  GetTaskSchema,
+  type GetTaskParams,
+  UpdateTaskSchema,
+  type UpdateTaskParams,
+} from "./schemas.js";
+
+type ToolSpec<P> = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: TSchema;
+  run: (client: TaskClient, params: P) => Promise<unknown>;
+};
+
+function registerTaskTool<P>(
+  api: OpenClawPluginApi,
+  spec: ToolSpec<P>,
+) {
+  api.registerTool(
+    {
+      name: spec.name,
+      label: spec.label,
+      description: spec.description,
+      parameters: spec.parameters,
+      async execute(_toolCallId, params) {
+        try {
+          return await withFeishuToolClient({
+            api,
+            toolName: spec.name,
+            requiredTool: "task",
+            run: async ({ client }) => json(await spec.run(client as TaskClient, params as P)),
+          });
+        } catch (err) {
+          return errorResult(err);
+        }
+      },
+    },
+    { name: spec.name },
+  );
+}
+
+export function registerFeishuTaskTools(api: OpenClawPluginApi) {
+  if (!api.config) {
+    api.logger.debug?.("feishu_task: No config available, skipping task tools");
+    return;
+  }
+
+  if (!hasFeishuToolEnabledForAnyAccount(api.config)) {
+    api.logger.debug?.("feishu_task: No Feishu accounts configured, skipping task tools");
+    return;
+  }
+
+  if (!hasFeishuToolEnabledForAnyAccount(api.config, "task")) {
+    api.logger.debug?.("feishu_task: task tools disabled in config");
+    return;
+  }
+
+  registerTaskTool<CreateTaskParams>(api, {
+    name: "feishu_task_create",
+    label: "Feishu Task Create",
+    description: "Create a Feishu task (task v2)",
+    parameters: CreateTaskSchema,
+    run: (client, params) => createTask(client, params),
+  });
+
+  registerTaskTool<DeleteTaskParams>(api, {
+    name: "feishu_task_delete",
+    label: "Feishu Task Delete",
+    description: "Delete a Feishu task by task_guid (task v2)",
+    parameters: DeleteTaskSchema,
+    run: (client, { task_guid }) => deleteTask(client, task_guid),
+  });
+
+  registerTaskTool<GetTaskParams>(api, {
+    name: "feishu_task_get",
+    label: "Feishu Task Get",
+    description: "Get Feishu task details by task_guid (task v2)",
+    parameters: GetTaskSchema,
+    run: (client, params) => getTask(client, params),
+  });
+
+  registerTaskTool<UpdateTaskParams>(api, {
+    name: "feishu_task_update",
+    label: "Feishu Task Update",
+    description: "Update a Feishu task by task_guid (task v2 patch)",
+    parameters: UpdateTaskSchema,
+    run: (client, params) => updateTask(client, params),
+  });
+
+  api.logger.debug?.("feishu_task: Registered 4 task tools");
+}

package/src/task-tools/schemas.ts

@@ -0,0 +1,138 @@
+import { Type } from "@sinclair/typebox";
+import type { TaskClient } from "./common.js";
+
+type TaskCreatePayload = NonNullable<Parameters<TaskClient["task"]["v2"]["task"]["create"]>[0]>;
+type TaskUpdatePayload = NonNullable<Parameters<TaskClient["task"]["v2"]["task"]["patch"]>[0]>;
+type TaskDeletePayload = NonNullable<Parameters<TaskClient["task"]["v2"]["task"]["delete"]>[0]>;
+type TaskGetPayload = NonNullable<Parameters<TaskClient["task"]["v2"]["task"]["get"]>[0]>;
+
+export type TaskCreateData = TaskCreatePayload["data"];
+export type TaskUpdateData = TaskUpdatePayload["data"];
+export type TaskUpdateTask = NonNullable<TaskUpdateData["task"]>;
+
+export type CreateTaskParams = {
+  summary: TaskCreateData["summary"];
+  description?: TaskCreateData["description"];
+  due?: TaskCreateData["due"];
+  start?: TaskCreateData["start"];
+  extra?: TaskCreateData["extra"];
+  completed_at?: TaskCreateData["completed_at"];
+  members?: TaskCreateData["members"];
+  repeat_rule?: TaskCreateData["repeat_rule"];
+  tasklists?: TaskCreateData["tasklists"];
+  mode?: TaskCreateData["mode"];
+  is_milestone?: TaskCreateData["is_milestone"];
+  user_id_type?: NonNullable<TaskCreatePayload["params"]>["user_id_type"];
+};
+
+export type DeleteTaskParams = {
+  task_guid: TaskDeletePayload["path"]["task_guid"];
+};
+
+export type GetTaskParams = {
+  task_guid: TaskGetPayload["path"]["task_guid"];
+  user_id_type?: NonNullable<TaskGetPayload["params"]>["user_id_type"];
+};
+
+export type UpdateTaskParams = {
+  task_guid: TaskUpdatePayload["path"]["task_guid"];
+  task: TaskUpdateTask;
+  update_fields?: TaskUpdateData["update_fields"];
+  user_id_type?: NonNullable<TaskUpdatePayload["params"]>["user_id_type"];
+};
+
+const TaskDateSchema = Type.Object({
+  timestamp: Type.Optional(
+    Type.String({
+      description:
+        "Unix timestamp in milliseconds (string), e.g. \"1735689600000\" (13-digit ms)",
+    }),
+  ),
+  is_all_day: Type.Optional(Type.Boolean({ description: "Whether this is an all-day date" })),
+});
+
+const TaskMemberSchema = Type.Object({
+  id: Type.String({ description: "Member ID (with type controlled by user_id_type)" }),
+  type: Type.Optional(Type.String({ description: "Member type (usually \"user\")" })),
+  role: Type.String({ description: "Member role, e.g. \"assignee\"" }),
+  name: Type.Optional(Type.String({ description: "Optional display name" })),
+});
+
+const TasklistRefSchema = Type.Object({
+  tasklist_guid: Type.Optional(Type.String({ description: "Tasklist GUID" })),
+  section_guid: Type.Optional(Type.String({ description: "Section GUID in tasklist" })),
+});
+
+export const CreateTaskSchema = Type.Object({
+  summary: Type.String({ description: "Task title/summary" }),
+  description: Type.Optional(Type.String({ description: "Task description" })),
+  due: Type.Optional(TaskDateSchema),
+  start: Type.Optional(TaskDateSchema),
+  extra: Type.Optional(Type.String({ description: "Custom opaque metadata string" })),
+  completed_at: Type.Optional(
+    Type.String({
+      description: "Completion time as Unix timestamp in milliseconds (string, 13-digit ms)",
+    }),
+  ),
+  members: Type.Optional(Type.Array(TaskMemberSchema, { description: "Initial task members" })),
+  repeat_rule: Type.Optional(Type.String({ description: "Task repeat rule" })),
+  tasklists: Type.Optional(
+    Type.Array(TasklistRefSchema, { description: "Attach the task to tasklists/sections" }),
+  ),
+  mode: Type.Optional(Type.Number({ description: "Task mode value from Feishu Task API" })),
+  is_milestone: Type.Optional(Type.Boolean({ description: "Whether task is a milestone" })),
+  user_id_type: Type.Optional(
+    Type.String({
+      description: "User ID type for member IDs, e.g. open_id/user_id/union_id",
+    }),
+  ),
+});
+
+export const DeleteTaskSchema = Type.Object({
+  task_guid: Type.String({ description: "Task GUID to delete" }),
+});
+
+export const GetTaskSchema = Type.Object({
+  task_guid: Type.String({ description: "Task GUID to retrieve" }),
+  user_id_type: Type.Optional(
+    Type.String({
+      description: "User ID type in returned members, e.g. open_id/user_id/union_id",
+    }),
+  ),
+});
+
+const TaskUpdateContentSchema = Type.Object(
+  {
+    summary: Type.Optional(Type.String({ description: "Updated summary" })),
+    description: Type.Optional(Type.String({ description: "Updated description" })),
+    due: Type.Optional(TaskDateSchema),
+    start: Type.Optional(TaskDateSchema),
+    extra: Type.Optional(Type.String({ description: "Updated extra metadata" })),
+    completed_at: Type.Optional(
+      Type.String({
+        description: "Updated completion time (Unix timestamp in milliseconds, string, 13-digit ms)",
+      }),
+    ),
+    repeat_rule: Type.Optional(Type.String({ description: "Updated repeat rule" })),
+    mode: Type.Optional(Type.Number({ description: "Updated task mode" })),
+    is_milestone: Type.Optional(Type.Boolean({ description: "Updated milestone flag" })),
+  },
+  { minProperties: 1 },
+);
+
+export const UpdateTaskSchema = Type.Object({
+  task_guid: Type.String({ description: "Task GUID to update" }),
+  task: TaskUpdateContentSchema,
+  update_fields: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Fields to update. If omitted, this tool infers from keys in task (e.g. summary, description, due, start)",
+      minItems: 1,
+    }),
+  ),
+  user_id_type: Type.Optional(
+    Type.String({
+      description: "User ID type when task body contains user-related fields",
+    }),
+  ),
+});

package/src/task.ts

@@ -0,0 +1 @@
+export { registerFeishuTaskTools } from "./task-tools/register.js";