@bobotu/feishu-fork 0.1.0

package/src/bitable-tools/common.ts

@@ -0,0 +1,90 @@
+import { createFeishuClient } from "../client.js";
+import {
+  errorResult,
+  json,
+  runFeishuApiCall,
+  type FeishuApiResponse,
+} from "../tools-common/feishu-api.js";
+
+export type BitableClient = ReturnType<typeof createFeishuClient>;
+
+// SDK-derived payload types keep tool input strongly typed and aligned with upstream API changes.
+type AppTableFieldCreatePayload = NonNullable<
+  Parameters<BitableClient["bitable"]["appTableField"]["create"]>[0]
+>;
+type AppTableFieldUpdatePayload = NonNullable<
+  Parameters<BitableClient["bitable"]["appTableField"]["update"]>[0]
+>;
+
+export type BitableFieldCreateData = AppTableFieldCreatePayload["data"];
+export type BitableFieldUpdateData = AppTableFieldUpdatePayload["data"];
+export type BitableFieldDescription = NonNullable<BitableFieldCreateData["description"]>;
+
+export { json, errorResult };
+
+const RETRYABLE_BITABLE_ERROR_CODES = new Set<number>([
+  1254607, // Data not ready
+  1255040, // Request timeout
+  1254290, // Too many requests
+  1254291, // Write conflict
+]);
+
+const RETRY_BACKOFF_MS = [350, 900, 1800];
+
+export async function runBitableApiCall<T extends FeishuApiResponse>(
+  context: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  // Bitable APIs can briefly return "Data not ready" after writes.
+  // Retry only known transient codes with short backoff.
+  return runFeishuApiCall(context, fn, {
+    retryableCodes: RETRYABLE_BITABLE_ERROR_CODES,
+    backoffMs: RETRY_BACKOFF_MS,
+  });
+}
+
+const FIELD_TYPE_NAMES: Record<number, string> = {
+  1: "Text",
+  2: "Number",
+  3: "SingleSelect",
+  4: "MultiSelect",
+  5: "DateTime",
+  7: "Checkbox",
+  11: "User",
+  13: "Phone",
+  15: "URL",
+  17: "Attachment",
+  18: "SingleLink",
+  19: "Lookup",
+  20: "Formula",
+  21: "DuplexLink",
+  22: "Location",
+  23: "GroupChat",
+  1001: "CreatedTime",
+  1002: "ModifiedTime",
+  1003: "CreatedUser",
+  1004: "ModifiedUser",
+  1005: "AutoNumber",
+};
+
+export function formatField(field: {
+  field_id?: string;
+  field_name?: string;
+  type?: number;
+  is_primary?: boolean;
+  property?: unknown;
+  ui_type?: string;
+  is_hidden?: boolean;
+}) {
+  const typeName = field.type != null ? FIELD_TYPE_NAMES[field.type] || `type_${field.type}` : undefined;
+  return {
+    field_id: field.field_id,
+    field_name: field.field_name,
+    type: field.type,
+    ...(typeName && { type_name: typeName }),
+    is_primary: field.is_primary,
+    ui_type: field.ui_type,
+    is_hidden: field.is_hidden,
+    ...(field.property && { property: field.property }),
+  };
+}

package/src/bitable-tools/index.ts

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

package/src/bitable-tools/meta.ts

@@ -0,0 +1,80 @@
+import { runBitableApiCall, type BitableClient } from "./common.js";
+
+// Accept both native bitable URLs and wiki-embedded bitable URLs.
+function parseBitableUrl(url: string): { token: string; tableId?: string; isWiki: boolean } | null {
+  try {
+    const u = new URL(url);
+    const tableId = u.searchParams.get("table") ?? undefined;
+
+    const wikiMatch = u.pathname.match(/\/wiki\/([A-Za-z0-9]+)/);
+    if (wikiMatch) {
+      return { token: wikiMatch[1], tableId, isWiki: true };
+    }
+
+    const baseMatch = u.pathname.match(/\/base\/([A-Za-z0-9]+)/);
+    if (baseMatch) {
+      return { token: baseMatch[1], tableId, isWiki: false };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function getAppTokenFromWiki(client: BitableClient, nodeToken: string): Promise<string> {
+  // Wiki links expose a wiki node token; bitable APIs require app_token.
+  const res = await runBitableApiCall("wiki.space.getNode", () =>
+    client.wiki.space.getNode({
+      params: { token: nodeToken },
+    }),
+  );
+
+  const node = res.data?.node;
+  if (!node) throw new Error("Node not found");
+  if (node.obj_type !== "bitable") {
+    throw new Error(`Node is not a bitable (type: ${node.obj_type})`);
+  }
+
+  return node.obj_token!;
+}
+
+export async function getBitableMeta(client: BitableClient, url: string) {
+  const parsed = parseBitableUrl(url);
+  if (!parsed) {
+    throw new Error("Invalid URL format. Expected /base/XXX or /wiki/XXX URL");
+  }
+
+  const appToken = parsed.isWiki ? await getAppTokenFromWiki(client, parsed.token) : parsed.token;
+
+  const res = await runBitableApiCall("bitable.app.get", () =>
+    client.bitable.app.get({
+      path: { app_token: appToken },
+    }),
+  );
+
+  let tables: { table_id: string; name: string }[] = [];
+  if (!parsed.tableId) {
+    // If table is not specified in URL, return available tables to guide the next call.
+    const tablesRes = await runBitableApiCall("bitable.appTable.list", () =>
+      client.bitable.appTable.list({
+        path: { app_token: appToken },
+      }),
+    );
+    tables = (tablesRes.data?.items ?? []).map((t) => ({
+      table_id: t.table_id!,
+      name: t.name!,
+    }));
+  }
+
+  return {
+    app_token: appToken,
+    table_id: parsed.tableId,
+    name: res.data?.app?.name,
+    url_type: parsed.isWiki ? "wiki" : "base",
+    ...(tables.length > 0 && { tables }),
+    hint: parsed.tableId
+      ? `Use app_token="${appToken}" and table_id="${parsed.tableId}" for other bitable tools`
+      : `Use app_token="${appToken}" for other bitable tools. Select a table_id from the tables list.`,
+  };
+}

package/src/bitable-tools/register.ts

@@ -0,0 +1,195 @@
+import type { TSchema } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { hasFeishuToolEnabledForAnyAccount, withFeishuToolClient } from "../tools-common/tool-exec.js";
+import {
+  batchDeleteRecords,
+  createField,
+  createRecord,
+  deleteField,
+  deleteRecord,
+  getRecord,
+  listFields,
+  listRecords,
+  updateField,
+  updateRecord,
+} from "./actions.js";
+import { errorResult, json, type BitableClient } from "./common.js";
+import { getBitableMeta } from "./meta.js";
+import {
+  BatchDeleteRecordsSchema,
+  type BatchDeleteRecordsParams,
+  CreateFieldSchema,
+  type CreateFieldParams,
+  CreateRecordSchema,
+  type CreateRecordParams,
+  DeleteFieldSchema,
+  type DeleteFieldParams,
+  DeleteRecordSchema,
+  type DeleteRecordParams,
+  GetMetaSchema,
+  type GetMetaParams,
+  GetRecordSchema,
+  type GetRecordParams,
+  ListFieldsSchema,
+  type ListFieldsParams,
+  ListRecordsSchema,
+  type ListRecordsParams,
+  UpdateFieldSchema,
+  type UpdateFieldParams,
+  UpdateRecordSchema,
+  type UpdateRecordParams,
+} from "./schemas.js";
+
+type ToolSpec<P> = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: TSchema;
+  run: (client: BitableClient, params: P) => Promise<unknown>;
+};
+
+// Shared registration wrapper keeps all bitable tools consistent:
+// same response envelope and same error conversion path.
+function registerBitableTool<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,
+            run: async ({ client }) => json(await spec.run(client as BitableClient, params as P)),
+          });
+        } catch (err) {
+          return errorResult(err);
+        }
+      },
+    },
+    { name: spec.name },
+  );
+}
+
+export function registerFeishuBitableTools(api: OpenClawPluginApi) {
+  if (!api.config || !hasFeishuToolEnabledForAnyAccount(api.config)) {
+    api.logger.debug?.("feishu_bitable: Feishu credentials not configured, skipping bitable tools");
+    return;
+  }
+
+  // Bitable tools are globally registered once, but each execution resolves
+  // the effective account through withFeishuToolClient().
+  // Keep registration explicit and flat so each tool is easy to locate and modify.
+  registerBitableTool<GetMetaParams>(api, {
+    name: "feishu_bitable_get_meta",
+    label: "Feishu Bitable Get Meta",
+    description:
+      "Parse a Bitable URL and get app_token, table_id, and table list. Use this first when given a /wiki/ or /base/ URL.",
+    parameters: GetMetaSchema,
+    run: (client, { url }) => getBitableMeta(client, url),
+  });
+
+  registerBitableTool<ListFieldsParams>(api, {
+    name: "feishu_bitable_list_fields",
+    label: "Feishu Bitable List Fields",
+    description: "List all fields (columns) in a Bitable table with their types and properties",
+    parameters: ListFieldsSchema,
+    run: (client, { app_token, table_id }) => listFields(client, app_token, table_id),
+  });
+
+  registerBitableTool<ListRecordsParams>(api, {
+    name: "feishu_bitable_list_records",
+    label: "Feishu Bitable List Records",
+    description: "List records (rows) from a Bitable table with pagination support",
+    parameters: ListRecordsSchema,
+    run: (client, { app_token, table_id, page_size, page_token }) =>
+      listRecords(client, app_token, table_id, page_size, page_token),
+  });
+
+  registerBitableTool<CreateFieldParams>(api, {
+    name: "feishu_bitable_create_field",
+    label: "Feishu Bitable Create Field",
+    description: "Create a new field (column) in a Bitable table",
+    parameters: CreateFieldSchema,
+    run: (client, { app_token, table_id, field_name, type, property, description, ui_type }) =>
+      createField(client, app_token, table_id, {
+        field_name,
+        type,
+        property,
+        description,
+        ui_type,
+      }),
+  });
+
+  registerBitableTool<UpdateFieldParams>(api, {
+    name: "feishu_bitable_update_field",
+    label: "Feishu Bitable Update Field",
+    description: "Update an existing field (column) in a Bitable table",
+    parameters: UpdateFieldSchema,
+    run: (client, { app_token, table_id, field_id, field_name, type, property, description, ui_type }) =>
+      updateField(client, app_token, table_id, field_id, {
+        field_name,
+        type,
+        property,
+        description,
+        ui_type,
+      }),
+  });
+
+  registerBitableTool<DeleteFieldParams>(api, {
+    name: "feishu_bitable_delete_field",
+    label: "Feishu Bitable Delete Field",
+    description: "Delete a field (column) from a Bitable table",
+    parameters: DeleteFieldSchema,
+    run: (client, { app_token, table_id, field_id }) => deleteField(client, app_token, table_id, field_id),
+  });
+
+  registerBitableTool<GetRecordParams>(api, {
+    name: "feishu_bitable_get_record",
+    label: "Feishu Bitable Get Record",
+    description: "Get a single record by ID from a Bitable table",
+    parameters: GetRecordSchema,
+    run: (client, { app_token, table_id, record_id }) => getRecord(client, app_token, table_id, record_id),
+  });
+
+  registerBitableTool<CreateRecordParams>(api, {
+    name: "feishu_bitable_create_record",
+    label: "Feishu Bitable Create Record",
+    description: "Create a new record (row) in a Bitable table",
+    parameters: CreateRecordSchema,
+    run: (client, { app_token, table_id, fields }) => createRecord(client, app_token, table_id, fields),
+  });
+
+  registerBitableTool<UpdateRecordParams>(api, {
+    name: "feishu_bitable_update_record",
+    label: "Feishu Bitable Update Record",
+    description: "Update an existing record (row) in a Bitable table",
+    parameters: UpdateRecordSchema,
+    run: (client, { app_token, table_id, record_id, fields }) =>
+      updateRecord(client, app_token, table_id, record_id, fields),
+  });
+
+  registerBitableTool<DeleteRecordParams>(api, {
+    name: "feishu_bitable_delete_record",
+    label: "Feishu Bitable Delete Record",
+    description: "Delete a single record (row) from a Bitable table",
+    parameters: DeleteRecordSchema,
+    run: (client, { app_token, table_id, record_id }) => deleteRecord(client, app_token, table_id, record_id),
+  });
+
+  registerBitableTool<BatchDeleteRecordsParams>(api, {
+    name: "feishu_bitable_batch_delete_records",
+    label: "Feishu Bitable Batch Delete Records",
+    description: "Delete multiple records (rows) from a Bitable table in one request",
+    parameters: BatchDeleteRecordsSchema,
+    run: (client, { app_token, table_id, record_ids }) =>
+      batchDeleteRecords(client, app_token, table_id, record_ids),
+  });
+
+  api.logger.debug?.("feishu_bitable: Registered 11 bitable tools");
+}

package/src/bitable-tools/schemas.ts

@@ -0,0 +1,221 @@
+import { Type } from "@sinclair/typebox";
+import type {
+  BitableFieldCreateData,
+  BitableFieldDescription,
+  BitableFieldUpdateData,
+} from "./common.js";
+
+export type GetMetaParams = {
+  url: string;
+};
+
+export type ListFieldsParams = {
+  app_token: string;
+  table_id: string;
+};
+
+export type CreateFieldParams = {
+  app_token: string;
+  table_id: string;
+  field_name: BitableFieldCreateData["field_name"];
+  type: BitableFieldCreateData["type"];
+  property?: BitableFieldCreateData["property"];
+  description?: BitableFieldDescription;
+  ui_type?: BitableFieldCreateData["ui_type"];
+};
+
+export type UpdateFieldParams = {
+  app_token: string;
+  table_id: string;
+  field_id: string;
+  field_name: BitableFieldUpdateData["field_name"];
+  type: BitableFieldUpdateData["type"];
+  property?: BitableFieldUpdateData["property"];
+  description?: BitableFieldDescription;
+  ui_type?: BitableFieldUpdateData["ui_type"];
+};
+
+export type DeleteFieldParams = {
+  app_token: string;
+  table_id: string;
+  field_id: string;
+};
+
+export type ListRecordsParams = {
+  app_token: string;
+  table_id: string;
+  page_size?: number;
+  page_token?: string;
+};
+
+export type GetRecordParams = {
+  app_token: string;
+  table_id: string;
+  record_id: string;
+};
+
+export type CreateRecordParams = {
+  app_token: string;
+  table_id: string;
+  fields: Record<string, unknown>;
+};
+
+export type UpdateRecordParams = {
+  app_token: string;
+  table_id: string;
+  record_id: string;
+  fields: Record<string, unknown>;
+};
+
+export type DeleteRecordParams = {
+  app_token: string;
+  table_id: string;
+  record_id: string;
+};
+
+export type BatchDeleteRecordsParams = {
+  app_token: string;
+  table_id: string;
+  record_ids: string[];
+};
+
+export const GetMetaSchema = Type.Object({
+  url: Type.String({
+    description:
+      "Bitable URL. Supports both formats: /base/XXX?table=YYY or /wiki/XXX?table=YYY",
+  }),
+});
+
+export const ListFieldsSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+});
+
+export const CreateFieldSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  field_name: Type.String({ description: "Field name" }),
+  type: Type.Number({
+    description: "Field type ID (e.g., 1=Text, 2=Number, 3=SingleSelect, 4=MultiSelect)",
+  }),
+  property: Type.Optional(
+    Type.Record(Type.String(), Type.Any(), {
+      description:
+        "Optional field property object, pass-through to Feishu API (e.g., select options/date format)",
+    }),
+  ),
+  description: Type.Optional(
+    Type.Object(
+      {
+        disable_sync: Type.Optional(Type.Boolean()),
+        text: Type.Optional(Type.String()),
+      },
+      { description: "Optional field description metadata" },
+    ),
+  ),
+  ui_type: Type.Optional(
+    Type.String({ description: "Optional UI type override (e.g., Text, Number, SingleSelect)" }),
+  ),
+});
+
+export const UpdateFieldSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  field_id: Type.String({ description: "Field ID to update" }),
+  field_name: Type.String({ description: "Updated field name" }),
+  type: Type.Number({ description: "Updated field type ID" }),
+  property: Type.Optional(
+    Type.Record(Type.String(), Type.Any(), {
+      description: "Optional field property object, pass-through to Feishu API",
+    }),
+  ),
+  description: Type.Optional(
+    Type.Object(
+      {
+        disable_sync: Type.Optional(Type.Boolean()),
+        text: Type.Optional(Type.String()),
+      },
+      { description: "Optional field description metadata" },
+    ),
+  ),
+  ui_type: Type.Optional(Type.String({ description: "Optional UI type override" })),
+});
+
+export const DeleteFieldSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  field_id: Type.String({ description: "Field ID to delete" }),
+});
+
+export const ListRecordsSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  page_size: Type.Optional(
+    Type.Number({
+      description: "Number of records per page (1-500, default 100)",
+      minimum: 1,
+      maximum: 500,
+    }),
+  ),
+  page_token: Type.Optional(Type.String({ description: "Pagination token from previous response" })),
+});
+
+export const GetRecordSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  record_id: Type.String({ description: "Record ID to retrieve" }),
+});
+
+export const CreateRecordSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  fields: Type.Record(Type.String(), Type.Any(), {
+    description:
+      "Field values keyed by field name. Format by type: Text='string', Number=123, SingleSelect='Option', MultiSelect=['A','B'], DateTime=timestamp_ms, User=[{id:'ou_xxx'}], URL={text:'Display',link:'https://...'}",
+  }),
+});
+
+export const UpdateRecordSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  record_id: Type.String({ description: "Record ID to update" }),
+  fields: Type.Record(Type.String(), Type.Any(), {
+    description: "Field values to update (same format as create_record)",
+  }),
+});
+
+export const DeleteRecordSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  record_id: Type.String({ description: "Record ID to delete" }),
+});
+
+export const BatchDeleteRecordsSchema = Type.Object({
+  app_token: Type.String({
+    description: "Bitable app token (use feishu_bitable_get_meta to get from URL)",
+  }),
+  table_id: Type.String({ description: "Table ID (from URL: ?table=YYY)" }),
+  record_ids: Type.Array(Type.String(), {
+    description: "Record ID list to delete (max 500 per request)",
+    minItems: 1,
+    maxItems: 500,
+  }),
+});