feishu-doc-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 m1heng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# feishu-doc-cli
+
+CLI tool to read [Feishu Open Platform](https://open.feishu.cn) documentation as Markdown.
+
+Feishu developer docs live behind a SPA that AI coding agents cannot read directly. This tool exposes the docs through a simple CLI, outputting raw Markdown that agents (and humans) can consume.
+
+## Install
+
+```bash
+npm install -g feishu-doc-cli
+```
+
+Requires Node.js >= 18.
+
+## Usage
+
+### Read a document
+
+```bash
+feishu-doc read /home/intro
+```
+
+Output:
+
+```markdown
+# 开放平台概述
+
+> Path: /home/intro
+> Updated: 2025-11-28
+
+---
+
+(original Markdown content)
+```
+
+### Browse the document tree
+
+```bash
+feishu-doc tree --depth 2
+```
+
+```
+├── 📁 文档首页
+│   └── 📄 首页  → /home/index
+├── 📁 开发指南
+│   ├── 📁 平台简介
+│   ├── 📁 开发流程
+│   ...
+```
+
+Filter to a subtree:
+
+```bash
+feishu-doc tree "/uAjLw4CM/uYjL24iN/platform-overveiw" --depth 3
+```
+
+### Search documents by title
+
+```bash
+feishu-doc search "消息"
+```
+
+```
+Found 109 document(s):
+
+  发送消息
+    feishu-doc read "/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create"
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--lang zh\|en` | Language | `zh` |
+| `--depth <n>` | Tree display depth | unlimited |
+
+## Following links
+
+Documents contain links in various formats. **All of them work directly with `feishu-doc read`** — just copy the `href` value from any link in the content:
+
+```bash
+# /ssl:ttdoc/ links (most common in content)
+feishu-doc read "/ssl:ttdoc/ukTMukTMukTM/uMTNz4yM1MjLzUzM"
+
+# Full Feishu URLs
+feishu-doc read "https://open.feishu.cn/document/client-docs/intro"
+
+# Full Lark URLs
+feishu-doc read "https://open.larkoffice.com/document/client-docs/bot-v3/bot-overview"
+
+# /document/ paths
+feishu-doc read "/document/client-docs/intro"
+
+# API fullPath (as shown in tree output)
+feishu-doc read "/home/intro"
+```
+
+The CLI normalizes all formats internally. No need to manually convert.
+
+## How it works
+
+Feishu Open Platform exposes two public APIs (no authentication required):
+
+| API | Purpose |
+|-----|---------|
+| `GET /api/tools/docment/directory_list` | Full document tree (~925 KB JSON) |
+| `GET /document_portal/v1/document/get_detail?fullPath=<path>` | Document content in Markdown |
+
+This CLI is a thin wrapper around these two endpoints.
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,67 @@
+const BASE = "https://open.feishu.cn";
+/**
+ * Normalize any link format found in Feishu docs to an API-usable fullPath.
+ *
+ * Accepted inputs:
+ *   /ssl:ttdoc/xxx                           → /xxx
+ *   https://open.feishu.cn/document/xxx      → /xxx
+ *   https://open.larkoffice.com/document/xxx → /xxx
+ *   /document/xxx                            → /xxx
+ *   /xxx                                     → /xxx  (passthrough)
+ */
+export function normalizePath(input) {
+    let p = input.trim();
+    // Strip URL with anchor — keep only the path part
+    // e.g. https://open.feishu.cn/document/xxx#anchor → /xxx
+    for (const domain of [
+        "https://open.feishu.cn",
+        "https://open.larkoffice.com",
+    ]) {
+        if (p.startsWith(domain)) {
+            try {
+                p = new URL(p).pathname;
+            }
+            catch {
+                // Malformed URL — strip the domain prefix as fallback
+                p = p.slice(domain.length);
+            }
+            break;
+        }
+    }
+    // /ssl:ttdoc/xxx → /xxx
+    if (p.startsWith("/ssl:ttdoc/")) {
+        p = p.slice("/ssl:ttdoc".length);
+    }
+    // /document/xxx → /xxx
+    if (p.startsWith("/document/")) {
+        p = p.slice("/document".length);
+    }
+    // Ensure leading slash
+    if (!p.startsWith("/")) {
+        p = "/" + p;
+    }
+    return p;
+}
+function headers(lang) {
+    const locale = lang === "en" ? "en-US" : "zh-CN";
+    return { Cookie: `open_locale=${locale}` };
+}
+export async function fetchTree(lang) {
+    const res = await fetch(`${BASE}/api/tools/docment/directory_list`, {
+        headers: headers(lang),
+    });
+    const json = (await res.json());
+    if (json.code !== 0 || !json.data)
+        throw new Error(`API error: code ${json.code}`);
+    return json.data.items;
+}
+export async function fetchDoc(path, lang) {
+    const fullPath = normalizePath(path);
+    const url = `${BASE}/document_portal/v1/document/get_detail?fullPath=${encodeURIComponent(fullPath)}`;
+    const res = await fetch(url, { headers: headers(lang) });
+    const json = (await res.json());
+    if (json.code !== 0 || !json.data) {
+        throw new Error(`API error: ${json.msg || `code ${json.code}`} (fullPath: ${fullPath})`);
+    }
+    return json.data;
+}

package/dist/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { fetchTree, fetchDoc, normalizePath } from "./api.js";
+import { renderTree, searchTree, filterSubtree } from "./tree.js";
+function usage() {
+    console.log(`feishu-doc - Read Feishu Open Platform docs as Markdown
+
+Usage:
+  feishu-doc read <path>          Read a document
+  feishu-doc tree [path]          Show document tree
+  feishu-doc search <keyword>     Search document titles
+
+Options:
+  --lang zh|en    Language (default: zh)
+  --depth <n>     Tree display depth limit
+
+Path formats (all accepted by 'read'):
+  /home/intro
+  /ssl:ttdoc/ukTMukTMukTM/uMTNz4yM1MjLzUzM
+  /document/client-docs/intro
+  https://open.feishu.cn/document/client-docs/intro
+  https://open.larkoffice.com/document/client-docs/bot-v3/bot-overview
+
+Tip: Any link href found in document content can be passed directly to 'read'.`);
+    process.exit(0);
+}
+function parseArgs(argv) {
+    const args = [];
+    let lang = "zh";
+    let depth = Infinity;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--lang" && argv[i + 1]) {
+            lang = argv[++i];
+        }
+        else if (argv[i] === "--depth" && argv[i + 1]) {
+            const n = parseInt(argv[++i], 10);
+            if (Number.isFinite(n) && n > 0)
+                depth = n;
+        }
+        else if (argv[i] === "--help" || argv[i] === "-h") {
+            usage();
+        }
+        else {
+            args.push(argv[i]);
+        }
+    }
+    return { args, lang, depth };
+}
+async function cmdRead(path, lang) {
+    const doc = await fetchDoc(path, lang);
+    const date = new Date(doc.updateTime).toISOString().slice(0, 10);
+    console.log(`# ${doc.name}\n`);
+    console.log(`> Path: ${doc.fullPath}`);
+    console.log(`> Updated: ${date}\n`);
+    console.log("---\n");
+    console.log(doc.content);
+}
+async function cmdTree(lang, depth, path) {
+    const tree = await fetchTree(lang);
+    const nodes = path ? filterSubtree(tree, normalizePath(path)) : tree;
+    if (!nodes) {
+        console.error(`Path not found in tree: ${path}`);
+        process.exit(1);
+        return;
+    }
+    console.log(renderTree(nodes, depth));
+}
+async function cmdSearch(keyword, lang) {
+    const tree = await fetchTree(lang);
+    const results = searchTree(tree, keyword);
+    if (results.length === 0) {
+        console.log(`No documents found matching "${keyword}"`);
+        return;
+    }
+    console.log(`Found ${results.length} document(s):\n`);
+    for (const r of results) {
+        console.log(`  ${r.name}`);
+        console.log(`    feishu-doc read "${r.fullPath}"\n`);
+    }
+}
+async function main() {
+    const { args, lang, depth } = parseArgs(process.argv.slice(2));
+    const command = args[0];
+    if (!command)
+        usage();
+    switch (command) {
+        case "read": {
+            const path = args[1];
+            if (!path) {
+                console.error("Error: missing <path>\nUsage: feishu-doc read <path>");
+                process.exit(1);
+            }
+            await cmdRead(path, lang);
+            break;
+        }
+        case "tree": {
+            await cmdTree(lang, depth, args[1]);
+            break;
+        }
+        case "search": {
+            const keyword = args[1];
+            if (!keyword) {
+                console.error("Error: missing <keyword>\nUsage: feishu-doc search <keyword>");
+                process.exit(1);
+            }
+            await cmdSearch(keyword, lang);
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            usage();
+    }
+}
+main().catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});

package/dist/tree.js

@@ -0,0 +1,49 @@
+export function renderTree(nodes, maxDepth = Infinity, depth = 0, prefix = "") {
+    if (depth >= maxDepth)
+        return "";
+    const lines = [];
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        const isLast = i === nodes.length - 1;
+        const connector = isLast ? "└── " : "├── ";
+        const isDir = node.type === "DirectoryType";
+        const icon = isDir ? "📁" : "📄";
+        const pathHint = isDir ? "" : `  → ${node.fullPath}`;
+        lines.push(`${prefix}${connector}${icon} ${node.name}${pathHint}`);
+        if (node.items.length > 0) {
+            const childPrefix = prefix + (isLast ? "    " : "│   ");
+            const sub = renderTree(node.items, maxDepth, depth + 1, childPrefix);
+            if (sub)
+                lines.push(sub);
+        }
+    }
+    return lines.join("\n");
+}
+export function searchTree(nodes, keyword) {
+    const results = [];
+    const kw = keyword.toLowerCase();
+    function walk(items) {
+        for (const node of items) {
+            if (node.type === "DocumentType" &&
+                node.name.toLowerCase().includes(kw)) {
+                results.push({ name: node.name, fullPath: node.fullPath });
+            }
+            if (node.items.length > 0)
+                walk(node.items);
+        }
+    }
+    walk(nodes);
+    return results;
+}
+export function filterSubtree(nodes, path) {
+    for (const node of nodes) {
+        if (node.fullPath === path)
+            return [node];
+        if (node.items.length > 0) {
+            const found = filterSubtree(node.items, path);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "feishu-doc-cli",
+  "version": "0.1.0",
+  "description": "CLI tool to read Feishu Open Platform documentation as Markdown, designed for AI coding agents",
+  "type": "module",
+  "license": "MIT",
+  "author": "m1heng",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/m1heng/feishu-doc-cli"
+  },
+  "homepage": "https://github.com/m1heng/feishu-doc-cli#readme",
+  "keywords": [
+    "feishu",
+    "lark",
+    "documentation",
+    "cli",
+    "markdown",
+    "ai-agent",
+    "developer-tools"
+  ],
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "feishu-doc": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}