cc-lark 0.1.1

package/src/tools/wiki/space.ts

@@ -0,0 +1,152 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_wiki_space tool - Manage Feishu Wiki spaces.
+ *
+ * Actions: list, get, create
+ */
+
+import { z } from 'zod';
+import type { ToolRegistry } from '../index.js';
+import { LarkClient } from '../../core/lark-client.js';
+import { getValidAccessToken, NeedAuthorizationError } from '../../core/uat-client.js';
+import { assertLarkOk } from '../../core/api-error.js';
+import { json, jsonError, type ToolResult } from '../im/helpers.js';
+import { logger } from '../../utils/logger.js';
+
+const log = logger('tools:wiki:space');
+
+// Schemas
+const listActionSchema = {
+  action: z.literal('list').describe('List wiki spaces'),
+  page_size: z.number().min(1).max(50).optional().describe('Page size (default 10)'),
+  page_token: z.string().optional().describe('Pagination token'),
+};
+
+const getActionSchema = {
+  action: z.literal('get').describe('Get a wiki space'),
+  space_id: z.string().describe('Space ID'),
+};
+
+const createActionSchema = {
+  action: z.literal('create').describe('Create a wiki space'),
+  name: z.string().optional().describe('Space name'),
+  description: z.string().optional().describe('Space description'),
+};
+
+async function getAccessToken(context: { larkClient: LarkClient | null; config: import('../../core/types.js').FeishuConfig }): Promise<string | ToolResult> {
+  const { larkClient, config } = context;
+  if (!larkClient) return jsonError('LarkClient not initialized.');
+  const { appId, appSecret, brand } = config;
+  if (!appId || !appSecret) return jsonError('Missing FEISHU_APP_ID or FEISHU_APP_SECRET.');
+
+  const { listStoredTokens } = await import('../../core/token-store.js');
+  const tokens = await listStoredTokens(appId);
+  if (tokens.length === 0) return jsonError('No user authorization found.');
+  const userOpenId = tokens[0].userOpenId;
+
+  try {
+    return await getValidAccessToken({ userOpenId, appId, appSecret, domain: brand ?? 'feishu' });
+  } catch (err) {
+    if (err instanceof NeedAuthorizationError) return jsonError('User authorization expired.');
+    throw err;
+  }
+}
+
+export function registerWikiSpaceTool(registry: ToolRegistry): void {
+  registry.register({
+    name: 'feishu_wiki_space_list',
+    description: 'List Feishu wiki spaces.\n\nRequires OAuth authorization.',
+    inputSchema: listActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof listActionSchema>>>;
+      const { larkClient } = context;
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`list: page_size=${p.page_size ?? 10}`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      const res = await larkClient!.sdk.wiki.space.list(
+        { params: { page_size: p.page_size as any, page_token: p.page_token } },
+        opts
+      );
+      assertLarkOk(res);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const data = res.data as any;
+
+      return json({
+        spaces: data?.items,
+        has_more: data?.has_more,
+        page_token: data?.page_token,
+      });
+    },
+  });
+
+  registry.register({
+    name: 'feishu_wiki_space_get',
+    description: 'Get a Feishu wiki space by ID.\n\nRequires OAuth authorization.',
+    inputSchema: getActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof getActionSchema>>>;
+      const { larkClient } = context;
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`get: space_id=${p.space_id}`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      const res = await larkClient!.sdk.wiki.space.get(
+        { path: { space_id: p.space_id } },
+        opts
+      );
+      assertLarkOk(res);
+
+      return json({ space: res.data?.space });
+    },
+  });
+
+  registry.register({
+    name: 'feishu_wiki_space_create',
+    description: 'Create a Feishu wiki space.\n\nRequires OAuth authorization.',
+    inputSchema: createActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof createActionSchema>>>;
+      const { larkClient } = context;
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`create: name=${p.name ?? '(empty)'}`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const data: any = {};
+      if (p.name) data.name = p.name;
+      if (p.description) data.description = p.description;
+
+      const res = await larkClient!.sdk.wiki.space.create({ data }, opts);
+      assertLarkOk(res);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const spaceData = res.data?.space as any;
+
+      return json({ space: res.data?.space, space_id: spaceData?.space_id });
+    },
+  });
+
+  log.debug('feishu_wiki_space tools registered');
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Utils module exports for cc-lark MCP Server.
+ */
+
+export * from './logger.js';

package/src/utils/logger.ts

@@ -0,0 +1,132 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Simple logger utility for the cc-lark MCP Server.
+ *
+ * Provides prefixed logging with ANSI color support for console output.
+ * Adapted from openclaw-lark lark-logger for MCP Server architecture.
+ */
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+export interface Logger {
+  readonly subsystem: string;
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+  child(name: string): Logger;
+}
+
+// ---------------------------------------------------------------------------
+// ANSI colors
+// ---------------------------------------------------------------------------
+
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const GRAY = '\x1b[90m';
+const RESET = '\x1b[0m';
+
+// ---------------------------------------------------------------------------
+// Message formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a log message with optional metadata.
+ *
+ * @param prefix - Log prefix (subsystem tag)
+ * @param message - Log message
+ * @param meta - Optional metadata to include
+ * @returns Formatted message string
+ */
+function formatMessage(
+  prefix: string,
+  message: string,
+  meta: Record<string, unknown> | undefined
+): string {
+  if (!meta || Object.keys(meta).length === 0) {
+    return `${prefix} ${message}`;
+  }
+
+  const parts = Object.entries(meta)
+    .map(([k, v]) => {
+      if (v === undefined || v === null) return null;
+      if (typeof v === 'object') return `${k}=${JSON.stringify(v)}`;
+      return `${k}=${v}`;
+    })
+    .filter(Boolean);
+
+  return parts.length > 0 ? `${prefix} ${message} (${parts.join(', ')})` : `${prefix} ${message}`;
+}
+
+// ---------------------------------------------------------------------------
+// Logger implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new logger instance.
+ *
+ * @param subsystem - Subsystem name for log prefix
+ * @returns Logger instance
+ */
+function createLogger(subsystem: string): Logger {
+  const tag = `cc-lark/${subsystem}`;
+
+  return {
+    subsystem,
+
+    debug(message: string, meta?: Record<string, unknown>): void {
+      const formatted = formatMessage(tag, message, meta);
+      console.debug(`${GRAY}[DEBUG]${RESET}`, formatted);
+    },
+
+    info(message: string, meta?: Record<string, unknown>): void {
+      const formatted = formatMessage(tag, message, meta);
+      console.log(`${CYAN}[INFO]${RESET}`, formatted);
+    },
+
+    warn(message: string, meta?: Record<string, unknown>): void {
+      const formatted = formatMessage(tag, message, meta);
+      console.warn(`${YELLOW}[WARN]${RESET}`, formatted);
+    },
+
+    error(message: string, meta?: Record<string, unknown>): void {
+      const formatted = formatMessage(tag, message, meta);
+      console.error(`${RED}[ERROR]${RESET}`, formatted);
+    },
+
+    child(name: string): Logger {
+      return createLogger(`${subsystem}/${name}`);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a logger for a subsystem.
+ *
+ * @param subsystem - Name of the subsystem (e.g., "api", "tools", "config")
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * const log = logger("api");
+ * log.info("Request started", { method: "GET", path: "/users" });
+ * log.error("Request failed", { error: "Connection timeout" });
+ * ```
+ */
+export function logger(subsystem: string): Logger {
+  return createLogger(subsystem);
+}
+
+/**
+ * Default logger instance for general use.
+ */
+export const defaultLogger = logger('core');

package/tests/core/config.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Tests for the configuration module.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  loadConfig,
+  validateConfig,
+  loadAndValidateConfig,
+  hasUserAccessToken,
+  getApiBaseUrl,
+  ENV_VARS,
+} from '../../src/core/config.js';
+
+describe('config', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    // Clear relevant environment variables before each test
+    Object.values(ENV_VARS).forEach(key => {
+      delete process.env[key];
+    });
+  });
+
+  afterEach(() => {
+    // Restore original environment
+    Object.values(ENV_VARS).forEach(key => {
+      delete process.env[key];
+    });
+    Object.entries(originalEnv).forEach(([key, value]) => {
+      if (value !== undefined) {
+        process.env[key] = value;
+      }
+    });
+  });
+
+  describe('loadConfig', () => {
+    it('should load configuration from environment variables', () => {
+      process.env[ENV_VARS.APP_ID] = 'test-app-id';
+      process.env[ENV_VARS.APP_SECRET] = 'test-app-secret';
+      process.env[ENV_VARS.USER_ACCESS_TOKEN] = 'test-user-token';
+      process.env[ENV_VARS.BRAND] = 'lark';
+
+      const config = loadConfig();
+
+      expect(config.appId).toBe('test-app-id');
+      expect(config.appSecret).toBe('test-app-secret');
+      expect(config.userAccessToken).toBe('test-user-token');
+      expect(config.brand).toBe('lark');
+    });
+
+    it('should return empty strings for missing required values', () => {
+      const config = loadConfig();
+
+      expect(config.appId).toBe('');
+      expect(config.appSecret).toBe('');
+      expect(config.userAccessToken).toBeUndefined();
+    });
+
+    it('should default brand to feishu if not specified', () => {
+      process.env[ENV_VARS.APP_ID] = 'test-app-id';
+      process.env[ENV_VARS.APP_SECRET] = 'test-app-secret';
+
+      const config = loadConfig();
+
+      expect(config.brand).toBe('feishu');
+    });
+
+    it('should load optional encrypt key and verification token', () => {
+      process.env[ENV_VARS.APP_ID] = 'test-app-id';
+      process.env[ENV_VARS.APP_SECRET] = 'test-app-secret';
+      process.env[ENV_VARS.ENCRYPT_KEY] = 'test-encrypt-key';
+      process.env[ENV_VARS.VERIFICATION_TOKEN] = 'test-verification-token';
+
+      const config = loadConfig();
+
+      expect(config.encryptKey).toBe('test-encrypt-key');
+      expect(config.verificationToken).toBe('test-verification-token');
+    });
+  });
+
+  describe('validateConfig', () => {
+    it('should pass validation with valid config', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: 'test-app-secret',
+        brand: 'feishu' as const,
+      };
+
+      const result = validateConfig(config);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+      expect(result.config).toEqual(config);
+    });
+
+    it('should fail validation when appId is missing', () => {
+      const config = {
+        appId: '',
+        appSecret: 'test-app-secret',
+      };
+
+      const result = validateConfig(config);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(`Missing required environment variable: ${ENV_VARS.APP_ID}`);
+    });
+
+    it('should fail validation when appSecret is missing', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: '',
+      };
+
+      const result = validateConfig(config);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(`Missing required environment variable: ${ENV_VARS.APP_SECRET}`);
+    });
+
+    it('should fail validation for invalid brand value', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: 'test-app-secret',
+        brand: 'invalid-brand' as const,
+      };
+
+      const result = validateConfig(config);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]).toContain('Invalid FEISHU_BRAND value');
+    });
+
+    it('should accept custom HTTPS URL as brand', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: 'test-app-secret',
+        brand: 'https://custom.lark.com' as const,
+      };
+
+      const result = validateConfig(config);
+
+      expect(result.valid).toBe(true);
+    });
+
+    it('should accept "lark" as brand', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: 'test-app-secret',
+        brand: 'lark' as const,
+      };
+
+      const result = validateConfig(config);
+
+      expect(result.valid).toBe(true);
+    });
+
+    it('should report multiple validation errors', () => {
+      const config = {
+        appId: '',
+        appSecret: '',
+      };
+
+      const result = validateConfig(config);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(2);
+    });
+  });
+
+  describe('loadAndValidateConfig', () => {
+    it('should load and return valid config', () => {
+      process.env[ENV_VARS.APP_ID] = 'test-app-id';
+      process.env[ENV_VARS.APP_SECRET] = 'test-app-secret';
+
+      const config = loadAndValidateConfig();
+
+      expect(config.appId).toBe('test-app-id');
+      expect(config.appSecret).toBe('test-app-secret');
+    });
+
+    it('should throw error for invalid config', () => {
+      expect(() => loadAndValidateConfig()).toThrow('Invalid configuration');
+    });
+  });
+
+  describe('hasUserAccessToken', () => {
+    it('should return true when user access token is set', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: 'test-app-secret',
+        userAccessToken: 'test-token',
+      };
+
+      expect(hasUserAccessToken(config)).toBe(true);
+    });
+
+    it('should return false when user access token is not set', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: 'test-app-secret',
+      };
+
+      expect(hasUserAccessToken(config)).toBe(false);
+    });
+
+    it('should return false when user access token is empty string', () => {
+      const config = {
+        appId: 'test-app-id',
+        appSecret: 'test-app-secret',
+        userAccessToken: '',
+      };
+
+      expect(hasUserAccessToken(config)).toBe(false);
+    });
+  });
+
+  describe('getApiBaseUrl', () => {
+    it('should return Feishu URL for feishu brand', () => {
+      expect(getApiBaseUrl('feishu')).toBe('https://open.feishu.cn/open-apis');
+    });
+
+    it('should return Lark URL for lark brand', () => {
+      expect(getApiBaseUrl('lark')).toBe('https://open.larksuite.com/open-apis');
+    });
+
+    it('should return custom URL for custom brand', () => {
+      expect(getApiBaseUrl('https://custom.api.com')).toBe('https://custom.api.com');
+    });
+
+    it('should default to feishu when no brand specified', () => {
+      expect(getApiBaseUrl()).toBe('https://open.feishu.cn/open-apis');
+    });
+  });
+});