@teamclaw/feishu-agent 1.0.0

package/src/core/config.ts

@@ -0,0 +1,174 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+
+export interface ContactCacheEntry {
+  name: string;
+  email?: string;
+  user_id?: string; // Also store user_id for lookup
+  union_id?: string;
+}
+
+export interface FeishuConfig {
+  appId: string;
+  appSecret: string;
+  userAccessToken?: string;
+  refreshToken?: string;
+}
+
+/**
+ * Returns the path to the global configuration file.
+ */
+export function getConfigPath(): string {
+  return join(homedir(), ".feishu-agent", "config.json");
+}
+
+/**
+ * Returns the path to the contact cache file.
+ */
+export function getContactCachePath(): string {
+  return join(homedir(), ".feishu-agent", "contact-cache.json");
+}
+
+/**
+ * Loads configuration from global config file.
+ */
+export async function loadConfig(): Promise<FeishuConfig> {
+  const configPath = getConfigPath();
+  let config: Partial<FeishuConfig> = {};
+
+  try {
+    const file = Bun.file(configPath);
+    if (await file.exists()) {
+      config = await file.json();
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return {
+    appId: config.appId || "",
+    appSecret: config.appSecret || "",
+    userAccessToken: config.userAccessToken,
+    refreshToken: config.refreshToken,
+  };
+}
+
+/**
+ * Saves the provided configuration to the global configuration file.
+ */
+export async function saveGlobalConfig(config: Partial<FeishuConfig>): Promise<void> {
+  const configPath = getConfigPath();
+  const configDir = join(homedir(), ".feishu-agent");
+
+  let currentConfig: Partial<FeishuConfig> = {};
+  try {
+    const file = Bun.file(configPath);
+    if (await file.exists()) {
+      currentConfig = await file.json();
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  const newConfig = { ...currentConfig, ...config };
+
+  await mkdir(configDir, { recursive: true });
+  await Bun.write(configPath, JSON.stringify(newConfig, null, 2));
+}
+
+/**
+ * Saves a contact entry to the contact cache.
+ * Key is union_id, value is name, email, and open_id.
+ */
+export async function saveContactToCache(unionId: string, entry: ContactCacheEntry): Promise<void> {
+  const cachePath = getContactCachePath();
+  const cacheDir = join(homedir(), ".feishu-agent");
+
+  let contactCache: Record<string, ContactCacheEntry> = {};
+  try {
+    const file = Bun.file(cachePath);
+    if (await file.exists()) {
+      contactCache = await file.json();
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  contactCache[unionId] = entry;
+
+  await mkdir(cacheDir, { recursive: true });
+  await Bun.write(cachePath, JSON.stringify(contactCache, null, 2));
+}
+
+/**
+ * Loads all cached contacts.
+ */
+export async function loadContactCache(): Promise<Record<string, ContactCacheEntry>> {
+  const cachePath = getContactCachePath();
+  try {
+    const file = Bun.file(cachePath);
+    if (await file.exists()) {
+      return await file.json();
+    }
+  } catch {
+    // Ignore errors
+  }
+  return {};
+}
+
+/**
+ * Searches cached contacts by name or email.
+ */
+export async function searchContactCache(query: string): Promise<{ union_id: string; user_id?: string; name: string; email?: string }[]> {
+  const cache = await loadContactCache();
+
+  if (!query) return [];
+
+  const lowerQuery = query.toLowerCase();
+
+  const results: { union_id: string; user_id?: string; name: string; email?: string }[] = [];
+  for (const [unionId, entry] of Object.entries(cache)) {
+    if (
+      entry.name.toLowerCase().includes(lowerQuery) ||
+      (entry.email && entry.email.toLowerCase() === lowerQuery)
+    ) {
+      results.push({ union_id: unionId, user_id: entry.user_id, name: entry.name, email: entry.email });
+    }
+  }
+  return results;
+}
+
+/**
+ * Gets a contact from cache by union_id or user_id.
+ */
+export async function getContactFromCache(id: string): Promise<ContactCacheEntry | undefined> {
+  const cache = await loadContactCache();
+  // Direct lookup by union_id
+  if (cache[id]) return cache[id];
+  // Lookup by user_id
+  for (const [unionId, entry] of Object.entries(cache)) {
+    if (entry.user_id === id) return entry;
+  }
+  return undefined;
+}
+
+/**
+ * Get union_id by user_id or vice versa
+ */
+export async function resolveContactId(id: string): Promise<{ union_id: string; user_id?: string } | undefined> {
+  const cache = await loadContactCache();
+  // If id looks like union_id (starts with on_), return it directly
+  if (id.startsWith('on_')) {
+    const entry = cache[id];
+    if (entry) return { union_id: id, user_id: entry.user_id };
+    return undefined;
+  }
+  // Otherwise, search for user_id
+  for (const [unionId, entry] of Object.entries(cache)) {
+    if (entry.user_id === id) {
+      return { union_id: unionId, user_id: id };
+    }
+  }
+  return undefined;
+}

package/src/core/contact.ts

@@ -0,0 +1,83 @@
+import { FeishuClient } from "./client";
+import { ListUsersResponse, UserInfo } from "../types";
+import { saveContactToCache, searchContactCache } from "./config";
+
+export class ContactManager {
+  private client: FeishuClient;
+
+  constructor(client: FeishuClient) {
+    this.client = client;
+  }
+
+  /**
+   * Search users by name or email.
+   * First checks cache, then falls back to API if no matches found.
+   */
+  async searchUser(query: string): Promise<UserInfo[]> {
+    if (!query) return [];
+
+    // 1. Try cache first
+    const cachedResults = await searchContactCache(query);
+    if (cachedResults.length > 0) {
+      console.log(`Found ${cachedResults.length} contact(s) in cache for "${query}"`);
+      return cachedResults.map(c => ({
+        user_id: c.user_id,
+        union_id: c.union_id,
+        name: c.name,
+        email: c.email,
+      }));
+    }
+
+    // 2. Fall back to API
+    console.log(`No cache matches for "${query}", searching Feishu API...`);
+
+    // List users from root department with union_id
+    const users = await this.listUsers("0");
+
+    // Filter by name or email
+    const lowerQuery = query.toLowerCase();
+    const results = users.filter(u =>
+      u.name.toLowerCase().includes(lowerQuery) ||
+      (u.en_name && u.en_name.toLowerCase().includes(lowerQuery)) ||
+      (u.email && u.email.toLowerCase().includes(lowerQuery))
+    );
+
+    // Cache the results (key = union_id)
+    for (const user of results) {
+      if (user.union_id && user.name) {
+        await saveContactToCache(user.union_id, {
+          name: user.name,
+          email: user.email,
+          user_id: user.user_id,
+          open_id: user.open_id,
+        });
+      }
+    }
+
+    if (results.length > 0) {
+      console.log(`Found ${results.length} contact(s), cached for future use.`);
+    }
+
+    return results;
+  }
+
+  /**
+   * List users in a specific department
+   */
+  async listUsers(departmentId: string = "0", pageSize: number = 50, pageToken?: string): Promise<UserInfo[]> {
+    const params: Record<string, string> = {
+      department_id: departmentId,
+      page_size: pageSize.toString(),
+      user_id_type: "union_id", // Request union_id for calendar attendee compatibility
+    };
+    if (pageToken) params.page_token = pageToken;
+
+    try {
+      const res = await this.client.get<ListUsersResponse["data"]>("/open-apis/contact/v3/users", params);
+      return res.items || [];
+    } catch (error) {
+      console.warn(`Failed to list users for department ${departmentId}:`, error);
+      return [];
+    }
+  }
+}

package/src/core/introspection.ts

@@ -0,0 +1,103 @@
+import { FeishuClient } from "./client";
+import { ListTablesResponse, ListFieldsResponse, FeishuTable, FeishuField } from "../types";
+
+export interface Schema {
+  baseToken: string;
+  tables: TableSchema[];
+}
+
+export interface TableSchema {
+  id: string;
+  name: string;
+  fields: FeishuField[];
+}
+
+export class IntrospectionEngine {
+  private client: FeishuClient;
+
+  constructor(client: FeishuClient) {
+    this.client = client;
+  }
+
+  async introspect(baseToken: string, onProgress?: (msg: string) => void): Promise<Schema> {
+    const tables = await this.listTables(baseToken, onProgress);
+    
+    const tableSchemas: TableSchema[] = await Promise.all(
+      tables.map(async (table) => {
+        onProgress?.(`Fetching fields for table ${table.name} (${table.table_id})...`);
+        const fields = await this.listFields(baseToken, table.table_id);
+        return {
+          id: table.table_id,
+          name: table.name,
+          fields,
+        };
+      })
+    );
+
+    return {
+      baseToken,
+      tables: tableSchemas,
+    };
+  }
+
+  private async listTables(baseToken: string, onProgress?: (msg: string) => void): Promise<FeishuTable[]> {
+    onProgress?.("Fetching tables list...");
+    let hasMore = true;
+    let pageToken = "";
+    const allTables: FeishuTable[] = [];
+
+    while (hasMore) {
+      const query: Record<string, string> = {};
+      if (pageToken) query.page_token = pageToken;
+
+      const data = await this.client.get<ListTablesResponse["data"]>(
+        `/open-apis/bitable/v1/apps/${baseToken}/tables`,
+        query
+      );
+
+      if (data.items) {
+        allTables.push(...data.items);
+      }
+
+      if (hasMore && !data.page_token) {
+         break; // Safety break
+      }
+
+      hasMore = data.has_more;
+      pageToken = data.page_token;
+    }
+
+    onProgress?.(`Found ${allTables.length} tables.`);
+    return allTables;
+  }
+
+  private async listFields(baseToken: string, tableId: string): Promise<FeishuField[]> {
+    let hasMore = true;
+    let pageToken = "";
+    const allFields: FeishuField[] = [];
+
+    while (hasMore) {
+      const query: Record<string, string> = {};
+      if (pageToken) query.page_token = pageToken;
+
+      const data = await this.client.get<ListFieldsResponse["data"]>(
+        `/open-apis/bitable/v1/apps/${baseToken}/tables/${tableId}/fields`,
+        query
+      );
+
+      if (data.items) {
+        allFields.push(...data.items);
+      }
+
+      if (hasMore && !data.page_token) {
+         break; // Safety break
+      }
+
+      hasMore = data.has_more;
+      pageToken = data.page_token;
+    }
+
+    return allFields;
+  }
+
+}

package/src/core/todo.ts

@@ -0,0 +1,109 @@
+import { FeishuClient } from "./client";
+
+export interface TodoItem {
+  record_id: string;
+  fields: {
+    Title: string;
+    Done: boolean;
+    Priority?: "High" | "Medium" | "Low";
+    [key: string]: any;
+  };
+}
+
+export class TodoManager {
+  private client: FeishuClient;
+  private appToken: string;
+  private tableId?: string;
+
+  constructor(client: FeishuClient, appToken: string) {
+    this.client = client;
+    this.appToken = appToken;
+  }
+
+  /**
+   * Find a table by name, or return the first table if no name provided.
+   */
+  async findTable(tableName: string = "Todo"): Promise<string> {
+    if (this.tableId) return this.tableId;
+
+    let pageToken = "";
+    let hasMore = true;
+
+    while (hasMore) {
+      const res: any = await this.client.get(`/open-apis/bitable/v1/apps/${this.appToken}/tables`, {
+        page_token: pageToken,
+        page_size: "100"
+      });
+      
+      const tables = res.data.items || [];
+      const target = tables.find((t: any) => t.name === tableName);
+      
+      if (target) {
+        this.tableId = target.table_id;
+        return target.table_id;
+      }
+
+      hasMore = res.data.has_more;
+      pageToken = res.data.page_token;
+    }
+
+    throw new Error(`Table "${tableName}" not found in Base ${this.appToken}`);
+  }
+
+  async listTodos(viewId?: string): Promise<TodoItem[]> {
+    const tableId = await this.findTable();
+    const params: Record<string, string> = { page_size: "100" };
+    if (viewId) params.view_id = viewId;
+
+    // Filter by formula could be added here if needed
+    // params.filter = 'CurrentValue.[Done]=FALSE()'; 
+
+    const res: any = await this.client.get(
+      `/open-apis/bitable/v1/apps/${this.appToken}/tables/${tableId}/records`, 
+      params
+    );
+
+    return (res.data.items || []).map((item: any) => ({
+      record_id: item.record_id,
+      fields: item.fields
+    }));
+  }
+
+  async createTodo(title: string, priority: string = "Medium"): Promise<TodoItem> {
+    const tableId = await this.findTable();
+    const body = {
+      fields: {
+        "Title": title,
+        "Done": false,
+        "Priority": priority
+      }
+    };
+
+    const res: any = await this.client.post(
+      `/open-apis/bitable/v1/apps/${this.appToken}/tables/${tableId}/records`,
+      body
+    );
+
+    return {
+      record_id: res.data.record.record_id,
+      fields: res.data.record.fields
+    };
+  }
+
+  async markDone(recordId: string): Promise<void> {
+    const tableId = await this.findTable();
+    const body = {
+      fields: {
+        "Done": true
+      }
+    };
+    
+    await this.client.request(
+        `/open-apis/bitable/v1/apps/${this.appToken}/tables/${tableId}/records/${recordId}`,
+        {
+            method: "PUT",
+            body: JSON.stringify(body)
+        }
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { setupCommand } from "./cli/commands/setup";
+import { authCommand } from "./cli/commands/auth";
+import { whoamiCommand } from "./cli/commands/whoami";
+import { loadConfig } from "./core/config";
+import { createConfigCommands } from "./cli/commands/config";
+import { createCalendarCommands } from "./cli/commands/calendar";
+import { createTodoCommands } from "./cli/commands/todo";
+import { createContactCommands } from "./cli/commands/contact";
+
+async function main() {
+  const program = new Command();
+
+  program
+    .name("feishu_agent")
+    .description("Feishu Agent CLI for AI assistants")
+    .version("1.0.0");
+
+  program
+    .command("setup")
+    .description("Initialize configuration")
+    .action(setupCommand);
+
+  program
+    .command("auth")
+    .description("Authenticate with Feishu OAuth")
+    .action(authCommand);
+
+  program
+    .command("whoami")
+    .description("Show current user info")
+    .action(whoamiCommand);
+
+  // Load config for commands that need it
+  const config = await loadConfig();
+
+  // Config subcommand group
+  const configCmd = program
+    .command("config")
+    .description("Manage configuration");
+  createConfigCommands(configCmd);
+
+  // Calendar subcommand group
+  const calendarCmd = program
+    .command("calendar")
+    .description("Manage calendar events");
+  createCalendarCommands(calendarCmd, config);
+
+  // Todo subcommand group
+  const todoCmd = program
+    .command("todo")
+    .description("Manage todos");
+  createTodoCommands(todoCmd, config);
+
+  // Contact subcommand group
+  const contactCmd = program
+    .command("contact")
+    .description("Manage contacts");
+  createContactCommands(contactCmd, config);
+
+  await program.parseAsync();
+}
+
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});
+
+// Export modules for library usage
+export * from "./core/client";
+export * from "./core/auth-manager";
+export * from "./core/calendar";
+export * from "./core/contact";
+export * from "./core/todo";
+export * from "./types";