mooncat-lark

Project-oriented Lark/Feishu SDK + CLI. Not a daemon — independent of channel/NATS. The difference vs the official SDK is that it fixes the few annoying things every project re-does:

1. bot/app credential config
2. user_access_token login & refresh(device flow,扫码登录)
3. default admin notify recipient
4. user/group aliases
5. quick IM notify
6. Base create / field semantics / collaborators
7. Drive upload + import file as online doc

Install

npm install mooncat-lark

One config file

// mooncat-lark.config.json
{
  "domain": "feishu",
  "bot": { "appId": "${LARK_APP_ID}", "appSecret": "${LARK_APP_SECRET}" },
  "admin": { "openId": "ou_xxx", "name": "管理员" },
  "contacts": {
    "users": { "张三": "ou_xxx" },
    "groups": { "告警群": "oc_xxx" }
  },
  "base": { "collaborators": [] },
  "auth": { "userToken": null }
}

SDK

import { createLark } from "mooncat-lark";

const lark = createLark({ config: "mooncat-lark.config.json" });

await lark.notify("任务完成");                                  // -> admin
await lark.notify("失败", { to: [lark.to.group("告警群")] });

await lark.im.sendText("hello", lark.to.user("张三"));
const uploaded = await lark.drive.upload("report.pdf");
const doc = await lark.drive.importFile("summary.md", { type: "docx" });
const base = await lark.base.createApp("采集结果");

notify with no to delivers to config.admin — the single most common case for unattended flows, so it's the default.

CLI

mooncat-lark init                          # 生成 mooncat-lark.config.json
mooncat-lark login                         # 扫码建应用 + 用户登录(零配置,凭证自动写入)
mooncat-lark login --app-id X --app-secret-stdin  # 已有应用直接填(不扫码建应用)
mooncat-lark notify "任务完成"             # 发给 admin(=首个登录用户)
mooncat-lark notify "fail" --to-group 告警群
mooncat-lark user 张三 ou_xxx              # 加用户别名
mooncat-lark group 告警群 oc_xxx           # 加群别名
mooncat-lark whoami                        # 查当前登录用户

正确顺序

1. init — 生成 config 骨架
2. login — 扫码建应用 + 用户登录(零配置)。无凭证时自动 requestAppRegistration 扫码创建飞书应用拿到 appId/appSecret,再 device flow 用户授权。已有应用用 --app-id。首个登录用户自动设为 admin(默认通知接收人)
3. notify — 发消息测试(bot 身份,用登录时建立的 app 凭证)
4. user / group — 加联系人/群别名

login 不需要预先配 bot 凭证——无凭证时它扫码建应用自动拿凭证。已有手建应用则用 --app-id 跳过建应用段。

Relationship to channel

mooncat-lark is independent. It sends to Lark directly. If you later need a message-bus bridge, build mooncat-channel-lark that depends on mooncat-lark — never the reverse.

Status

v0.3 — config + facade + notify + CLI(init/login/admin/user/group/notify/whoami)。 login 两段式(扫码建应用 + device flow),用户零配置。 device flow login 已接通(userAuth device flow + token store)。 Business modules(Base/Drive/Docx/Chat/Contact)migrated from libs/lark。

Origin: extracted from mooncat/libs/lark — no runtime/channel dependencies.