@geoly-ai/social-hub-cli 0.3.41 → 0.3.42

package/dist/watchlists-list-filters.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=watchlists-list-filters.test.d.ts.map

package/dist/watchlists-list-filters.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchlists-list-filters.test.d.ts","sourceRoot":"","sources":["../src/watchlists-list-filters.test.ts"],"names":[],"mappings":""}

package/dist/watchlists-list-filters.test.js

@@ -0,0 +1,143 @@
+/**
+ * 五层同步补口:`intel watchlists-list` 的服务端筛选参数。
+ *
+ * 服务端(contracts/db/api)与 SDK 在 cf63e6b4 已经支持
+ * subredditQuery / tag / monitorState / sortBy / sortDir,并顺带补上此前漏传的
+ * status / brandId / industryKeys —— 缺的只有 CLI 这一层。
+ *
+ * 🔴 本文件跑的是**真实 handler**,不是「断言选项已注册」。
+ * 只断言注册挡不住本任务最可能的静默失败形状:**解析了但没往下传**
+ * (`.option()` 写了、`listSubredditWatchlists({...})` 里忘了那一行)——
+ * 那种情况下 `--help` 看着完全正常、命令也不报错,只是筛选悄悄没生效,
+ * 返回的是**未筛选的全量**,读起来完全可信。
+ *
+ * 🔴 monitorState 是**三值**不是布尔。软停语义:
+ *   · disabled = 加过监听后停了(配置行还在)
+ *   · never    = 压根没加过
+ * 用户提这个需求要的正是这个区别,所以这里除了「三个值都能透传」之外,
+ * 还钉死「布尔值被拒且错误信息讲清三值」——防的是后人把它简化成 `--monitored`。
+ */
+import { beforeAll, afterEach, describe, expect, it, vi } from "vitest";
+const listSubredditWatchlists = vi
+    .fn()
+    .mockResolvedValue({ items: [], total: 0 });
+vi.mock("@geoly-ai/social-hub-sdk", () => ({
+    SocialHubClient: vi.fn(),
+    getSocialHubHealth: vi.fn(),
+}));
+vi.mock("./client.js", () => ({
+    requireClient: () => ({ listSubredditWatchlists }),
+    resolveTeamId: (t) => t ?? "team-1",
+    getBaseUrl: () => "http://localhost",
+}));
+let program;
+let cmd;
+/**
+ * ⚠️ commander 把上一次 parse 的 option 值**留在同一个 command 实例上**,
+ * 而真实 CLI 每次都是新进程。不清的话「不传 --subreddit-query」会读到上一个
+ * 用例残留的值 —— 那既不是真实行为,也会让用例顺序变成隐性依赖
+ * (`accounts-list-offset.test.ts` 是靠「把两次 parse 塞进同一个用例、不传的放前面」
+ * 绕开的;这里参数多,绕不动,直接清)。
+ */
+const resetOpts = () => {
+    for (const opt of cmd.options)
+        cmd.setOptionValue(opt.attributeName(), opt.defaultValue);
+};
+const run = (...args) => {
+    resetOpts();
+    return program.parseAsync([
+        "node",
+        "social-hub",
+        "intelligence",
+        "watchlists-list",
+        ...args,
+    ]);
+};
+/** 最后一次调用收到的参数对象。 */
+const lastArgs = () => listSubredditWatchlists.mock.calls.at(-1)?.[0];
+beforeAll(async () => {
+    program = (await import("./index.js")).program;
+    const intel = program.commands.find((c) => c.name() === "intelligence");
+    const found = intel?.commands.find((c) => c.name() === "watchlists-list");
+    // 正向对照:命令真的存在。找不到时下面 resetOpts 会静默变成空循环,
+    // 于是整份用例退化成「跑了个不存在的命令」而依然可能全绿。
+    if (!found)
+        throw new Error("intelligence watchlists-list 命令没找到");
+    cmd = found;
+    vi.spyOn(console, "log").mockImplementation(() => { });
+}, 30000);
+afterEach(() => {
+    listSubredditWatchlists.mockClear();
+});
+describe("intelligence watchlists-list 服务端筛选参数", () => {
+    it("🔴 每个筛选参数都真的传到了 SDK;不传时不发送(保持服务端默认)", async () => {
+        await run();
+        // 正向对照:handler 确实跑到了、确实带着默认分页调了 SDK。
+        // 没有这一条的话,下面一串 toBeUndefined() 在「命令压根没执行」时也全绿。
+        expect(listSubredditWatchlists).toHaveBeenCalledTimes(1);
+        expect(lastArgs()).toMatchObject({ limit: 100, offset: 0 });
+        for (const key of [
+            "subredditQuery",
+            "status",
+            "brandId",
+            "industryKeys",
+            "tag",
+            "monitorState",
+            "sortBy",
+            "sortDir",
+        ])
+            expect(lastArgs()[key], `${key} 不传时不应发送`).toBeUndefined();
+        await run("--subreddit-query", "garden", "--status", "active", "--brand", "11111111-1111-4111-8111-111111111111", "--industry-keys", "home,garden", "--tag", "seed", "--monitor-state", "disabled", "--sort-by", "monitorLastObservedAt", "--sort-dir", "asc", "--limit", "25", "--offset", "50");
+        expect(listSubredditWatchlists).toHaveBeenCalledTimes(2);
+        expect(lastArgs()).toMatchObject({
+            subredditQuery: "garden",
+            status: "active",
+            brandId: "11111111-1111-4111-8111-111111111111",
+            industryKeys: "home,garden",
+            tag: "seed",
+            monitorState: "disabled",
+            sortBy: "monitorLastObservedAt",
+            sortDir: "asc",
+            limit: 25,
+            offset: 50,
+        });
+    });
+    it("--subreddit(精确)与 --subreddit-query(子串)是两个独立谓词,不许互相顶替", async () => {
+        await run("--subreddit", "r/gardening");
+        expect(lastArgs()).toMatchObject({ subreddit: "r/gardening" });
+        // 变异形状:把 subredditQuery 接到 opts.subreddit 上(或反过来)。
+        expect(lastArgs().subredditQuery).toBeUndefined();
+        await run("--subreddit-query", "garden");
+        expect(lastArgs()).toMatchObject({ subredditQuery: "garden" });
+        expect(lastArgs().subreddit).toBeUndefined();
+    });
+    describe("🔴 monitorState 三值(⛔ 不是布尔)", () => {
+        it.each(["enabled", "disabled", "never"])("%s 原样透传为字符串", async (state) => {
+            await run("--monitor-state", state);
+            expect(lastArgs().monitorState).toBe(state);
+            // 变异形状:`monitorState: opts.monitorState === "enabled"` 这类布尔退化。
+            // 只写 toBe(state) 也能抓到,这条是把「类型」这层意图写死,防后人改成布尔。
+            expect(typeof lastArgs().monitorState).toBe("string");
+        });
+        it.each(["true", "false", "1", "monitored", ""])("⛔ 布尔式/拼错的值 %j 直接报错,不静默落到某一档", async (bad) => {
+            await expect(run("--monitor-state", bad)).rejects.toThrow(/--monitor-state/);
+            // 正向对照:报错是「拒绝了」,不是「转发了一个坏值」。
+            expect(listSubredditWatchlists).not.toHaveBeenCalled();
+        });
+        it("错误信息必须讲清 disabled 与 never 的区别(不然读者仍会以为是布尔)", async () => {
+            // parseAsync 成功时 resolve 的是 Command,所以这里显式把两种结局收成 unknown,
+            // 再由下面的 toBeInstanceOf 判定 —— ⛔ 不要直接 `as Error`,那会让
+            // 「命令没报错」这种情况静默走到 err.message 上(undefined.contains 反而报别的错)。
+            const err = await run("--monitor-state", "true").then((ok) => ok, (e) => e);
+            // 正向对照:确实拿到了一个 Error(而不是命令压根没报错、下面对 undefined 断言)。
+            expect(err).toBeInstanceOf(Error);
+            const message = err.message;
+            for (const token of ["enabled", "disabled", "never"])
+                expect(message).toContain(token);
+            // 光列三个词还不够 —— 必须说清「停了的」和「从没加过」不是一回事。
+            expect(message).toMatch(/软停|配置行/);
+            expect(message).toMatch(/没加过|新建配置行/);
+        });
+    });
+});
+//# sourceMappingURL=watchlists-list-filters.test.js.map

package/dist/watchlists-list-filters.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchlists-list-filters.test.js","sourceRoot":"","sources":["../src/watchlists-list-filters.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/social-hub-cli",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "type": "module",
   "description": "social-hub CLI for Social Ops Hub",
   "repository": {
@@ -23,7 +23,7 @@
   "dependencies": {
     "commander": "^12.1.0",
     "@geoly-ai/social-hub-authz": "0.0.20",
-    "@geoly-ai/social-hub-sdk": "0.1.13"
+    "@geoly-ai/social-hub-sdk": "0.1.15"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/skills/integrity.json

@@ -4,7 +4,7 @@
   "fileCount": 1656,
   "files": {
     "README.md": "5246d4ae2712e3e656b101041929183d7ae7f8ea487dacf5854187826ab7c335",
-    "manifest.json": "d3ee4c48236d3a84bf5f2e77f2364a3fa1bfb84a0ce5761e33bbf471d747cc31",
+    "manifest.json": "511a9d10759fb3093bd091a04cf613743967548b9b12d623cae22235571fd7e9",
     "reddit-answers-research/SKILL.md": "ab6fd12eeb2fef4dc31a6f3c21a84810d6b5bdb309f130bcdc9eb902f075294a",
     "reddit-answers-research/references/browser-playbook.md": "a8f61d3d43ca93d46dadc8a092a515ddcd32df12fb1d08d334cce2e02709d915",
     "reddit-answers-research/references/report-template.md": "9aa9acf555ba8b2ca503bdbdf5750a5f53c66e19989bf6807fa6200c7317e306",
@@ -1643,7 +1643,7 @@
     "social-hub-content-review/SKILL.md": "6d10a84ab56552fd953863b97978bddc0e925e3a2667d64a7a4c51e33a3ddb58",
     "social-hub-events-observability/SKILL.md": "f4c17487c64bb1f48381d8d60e97cfa160a94a0f120153b1c0e798a0c7ee7ebe",
     "social-hub-graph-compliance/SKILL.md": "2270aeb321733f0318f75da4838ca1ca03996c6cac59e5a12f7152bd1ecdfa26",
-    "social-hub-intelligence/SKILL.md": "c543ad315abad7455c93e348c8bdb1601070d55845d96bac43a5beb29eaba13c",
+    "social-hub-intelligence/SKILL.md": "632e6ad7fe92cf82c0b5e9e01c2ea5d6aff94871384c5e39d8617fcd0663e877",
     "social-hub-migration/SKILL.md": "1c13f231bb81ae8d242c834eec93a499830481804c66f6dba95922972f56f9ce",
     "social-hub-notifications/SKILL.md": "f80f4cf2f9ef0dbf60bd6e8bb4ad7e27dc0ff1fe59f4c7e79e49cc691ed4be6a",
     "social-hub-openclaw-context/SKILL.md": "97c48f38f1f1a206c3af2af49fcd445a1cd5b78d4a9c805c2456de4ce98fec09",

package/skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "package": "social-ops-hub",
-  "cliVersion": "0.3.41",
+  "cliVersion": "0.3.42",
   "repository": "social-ops-hub",
   "publish": {
     "registry": "https://skill.sh",

package/skills/social-hub-intelligence/SKILL.md

@@ -197,7 +197,12 @@ installed_apps 7 天。
 ## Watchlists
 
 ```bash
-social-hub intelligence watchlists-list [--campaign <uuid>]
+social-hub intelligence watchlists-list [--campaign <uuid>] [--subreddit <name>] \
+  [--subreddit-query <text>] [--status active|paused|archived] [--brand <uuid>] \
+  [--industry-keys <k1,k2>] [--tag <tag>] \
+  [--monitor-state enabled|disabled|never] \
+  [--sort-by createdAt|subreddit|monitorLastObservedAt] [--sort-dir asc|desc] \
+  [-n 100] [--offset 0]
 social-hub intelligence watchlists-create -j '{"subreddit":"technology","tags":["core"]}'
 # 品牌洞察(VOC/SOV)用的监控池:显式绑定品牌 + 指定主行业
 social-hub intelligence watchlists-create -j '{"subreddit":"jewelry","primaryIndustryKey":"industry_pools__jewelry","brandIds":["<brand-uuid>"]}'
@@ -212,6 +217,40 @@ brand 池 > industry 池 > 其他,稳定排序;此前首匹配会把养号宠物
 品牌 VOC/SOV 扫描取"全局 + 绑定当前品牌"的池。做品牌洞察(如 Aporro)时创建
 watchlist 须显式传 `brandIds`。
 
+**筛选一律在服务端**(分页是 `limit/offset` + `total`)。⛔ 不要"拉一页回来自己过滤":
+那只过滤到**当前页**,筛完看到 3 条会以为总共就 3 条。板块多时用 `--offset` 翻页。
+
+**`--subreddit` 与 `--subreddit-query` 是两个谓词,别混**:前者**精确**匹配(板块详情
+聚合视图靠它拿到确定的那一行),后者是**子串**搜索(给"我想找个板块加监听"用)。
+两者都大小写不敏感、`r/` 前缀可省。`--tag` 是**精确包含**单个标签(不是子串)。
+`--industry-keys` 逗号分隔可多个。`--brand` 只返回**显式绑定**该品牌的池,**不含全局池**
+——想要"这个品牌实际会扫到的池",还得再查一次不带 `--brand` 的全局池并合并。
+
+### 🔴 `--monitor-state` 是**三值**,不是布尔
+
+停止监听是**软停**(`enabled=false`,配置行和观察 ledger 都还在),所以"没在监听"
+在业务上是**两种截然不同**的状态,`--monitor-state` 必须分开表达:
+
+| 值         | 含义                   | 要做什么才能恢复监听                                              |
+| ---------- | ---------------------- | ----------------------------------------------------------------- |
+| `enabled`  | 正在监听               | —                                                                 |
+| `disabled` | **加过监听、后来停了** | `monitors-enable` 直接重启;历史水位还在,不会重复报旧帖            |
+| `never`    | **压根没加过监听**     | `monitors-enable` 会**新建**配置行;该板块历史帖会被当成新帖报一遍 |
+
+⛔ 不要把它当成 `--monitored true/false` 用——CLI 会直接报错。想要"所有没在监听的",
+得**分两次查**(`disabled` 一次、`never` 一次),因为对这两批要采取的动作不一样:
+`disabled` 是"我停过它,要不要恢复";`never` 是"这个板块我还没碰过"。
+⚠️ 服务端也没有"合并版"的布尔筛选可用,别去猜一个 `--monitored`。
+
+**权限**:`--monitor-state` 与 `--sort-by monitorLastObservedAt` 属**系统级运维配置**面,
+受限主体(client)传任一个都会 **403**;同一道门也把 `monitorLastObservedAt` 字段从
+受限主体的响应里摘掉了。排序也算旁路——按它排序等于把"在监听的"全顶到前面。
+
+**排序**:`--sort-by createdAt|subreddit|monitorLastObservedAt`(缺省 `createdAt`)。
+⚠️ 不传 `--sort-dir` 时方向**随排序键而变**:`subreddit` 缺省 `asc`(字母序),
+其余缺省 `desc`(最新在前)。要稳定就显式传。
+⚠️ 分页仍是 offset,排序键的值在翻页期间变化时理论上会跨页漂移(当前规模几十行,可接受)。
+
 ## 板块新帖监听(定时抓 `/new` → 飞书卡片 @ 负责人)
 
 系统级(与 watchlist 同源,**无 `-t/--team`**)。cron 每 12h 一轮:抓已启用板块的