@geoly-ai/social-hub-sdk 0.1.14 → 0.1.16

package/dist/index.d.ts

@@ -722,6 +722,22 @@ export type ListSubredditWatchlistsParams = {
     campaignId?: string;
     /** 按板块名精确查归属(r/ 前缀可省,大小写不敏感)。 */
     subreddit?: string;
+    /** 板块名**子串**搜索(大小写不敏感,r/ 可省);与 `subreddit` 是两个独立谓词。 */
+    subredditQuery?: string;
+    /** ⚠️ 2026-09-09 之前本 SDK 方法**漏传**了服务端早就支持的 status/brandId/industryKeys。 */
+    status?: "active" | "paused" | "archived";
+    brandId?: string;
+    /** 逗号分隔的行业 key 列表(服务端自己 split)。 */
+    industryKeys?: string;
+    tag?: string;
+    /**
+     * 新帖监听状态。软停语义:`disabled` = 停过(配置行还在),`never` = 从没加过。
+     * ⚠️ 受限主体(client)传这个会 403 —— 监听是系统级运维配置。
+     */
+    monitorState?: "enabled" | "disabled" | "never";
+    /** ⚠️ `monitorLastObservedAt` 与 `monitorState` 同一道权限门。 */
+    sortBy?: "createdAt" | "subreddit" | "monitorLastObservedAt";
+    sortDir?: "asc" | "desc";
 };
 export type ListSubredditMonitorsParams = {
     limit?: number;
@@ -756,12 +772,30 @@ export type SubredditMonitorRuleScope = "title" | "body" | "both";
  * ⚠️ CJK 没有词边界概念,`word` 在 CJK 上退化为子串 —— 否则「咖啡」永远匹配不上「咖啡机」。
  */
 export type SubredditMonitorMatchMode = "word" | "substring" | "phrase";
+/**
+ * 规则极性(0171)。
+ * - `include`:命中它就算相关;
+ * - `exclude`:命中它就**撤销**同等或更低来源优先级的 include 命中
+ *   (优先级 manual > brand_keyword > expansion —— 模型扩出来的否定词不该把运营
+ *    亲手填的 include 词否掉)。
+ *
+ * ⚠️ exclude 规则**自己不产生命中**。一条 include 都没有的规则集会被服务端拒绝激活
+ *(409)—— 那等于把整个板块静音,而卡片上看起来只是「今天没有相关新帖」。
+ * ⚠️ 同一个 (term, scope, matchMode) 上**可以**同时存在 include 与 exclude 两条:
+ *「espresso 收进来、espresso martini 排出去」正是这个形状。
+ */
+export type SubredditMonitorRulePolarity = "include" | "exclude";
 export type SubredditMonitorKeywordRuleInput = {
     /** 原样字面值;服务端归一化(NFKC / 去重音 / 小写)后才进唯一键。 */
     term: string;
     scope?: SubredditMonitorRuleScope;
     matchMode?: SubredditMonitorMatchMode;
-    /** 只影响卡片里命中词的展示顺序,不影响是否命中(本期只做 include)。 */
+    /** 省略 = `include`。见 {@link SubredditMonitorRulePolarity}。 */
+    polarity?: SubredditMonitorRulePolarity;
+    /**
+     * 影响卡片里命中词的展示顺序;对 exclude 规则则决定「因为 X 被排除」里 X 的排序。
+     * ⚠️ 它**不是**打分阈值:命中与否是布尔判定,不存在「权重不够就不算命中」。
+     */
     weight?: number;
     /** 品牌词导入的**来源溯源**;⛔ 不建立同步语义。 */
     sourceBrandKeywordId?: string | null;
@@ -772,13 +806,89 @@ export type SubredditMonitorKeywordRule = Required<Pick<SubredditMonitorKeywordR
     ruleSetId: string;
     normalizedTerm: string;
     scope: SubredditMonitorRuleScope;
-    /** 本期只有 `include`(排除词是 P2,契约与 DDL 层都表达不出来)。 */
-    polarity: "include";
+    /** `include` / `exclude`(0171 起)。见 {@link SubredditMonitorRulePolarity}。 */
+    polarity: SubredditMonitorRulePolarity;
     matchMode: SubredditMonitorMatchMode;
     weight: number;
     sourceBrandKeywordId: string | null;
     sourceBrandKeywordValue: string | null;
 };
+/**
+ * 回放的逐帖判定。
+ * 🔴 `excluded` 与 `no_match` 是**两个不同的值**,⛔ 不得合并:
+ * `excluded` = 命中了 include 但被排除词否掉(去看排除词是不是配宽了);
+ * `no_match` = 一个 include 都没命中(去看 include 词是不是配窄了)。
+ */
+export type SubredditMonitorReplayDecision = "matched" | "indeterminate" | "excluded" | "no_match";
+export type SubredditMonitorReplayRun = {
+    id: string;
+    monitorId: string;
+    ruleSetId: string;
+    ruleSetVersion: number | null;
+    ruleHash: string | null;
+    windowStart: string;
+    windowEnd: string;
+    evaluatedCount: number;
+    matchedCount: number;
+    indeterminateCount: number;
+    /** 命中了 include 但被排除词否掉。⛔ 不含在 screenedOutCount 里。 */
+    excludedCount: number;
+    screenedOutCount: number;
+    /** 撞上硬顶。⚠️ **是布尔不是计数** —— 查询给不出准确的剩余数。 */
+    truncated: boolean;
+    note: string | null;
+    requestedBy: string | null;
+    createdAt: string;
+};
+export type SubredditMonitorReplayHit = {
+    id: string;
+    canonicalPermalink: string;
+    title: string | null;
+    postedAt: string | null;
+    decision: SubredditMonitorReplayDecision;
+    matchedTerms: string[];
+    matchedScopes: string[];
+    totalWeight: number;
+    bodyAvailability: string;
+    /** 造成撤销的排除词。`decision='excluded'` 时非空。 */
+    excludedByTerms: string[];
+    /** 正文拿不到 + 有正文域 exclude 规则 ⇒「该不该排除」判不了。 */
+    exclusionIndeterminate: boolean;
+    /** 当时**真实**账本里的判定;null = 当时没有账本行(见 originalAbsentReason)。 */
+    originalDecision: "matched" | "indeterminate" | null;
+    originalReportedAt: string | null;
+    originalRuleSetId: string | null;
+    /**
+     * 🔴 `originalDecision === null` 是多义的,这一位把它拆开:
+     * `screened_out` = 当时确实见过、只是判了不命中(账本对不命中一条都不写);
+     * `never_observed` = 当时根本没见过(还没开监听 / VOC 回灌进来的)。
+     * ⛔ 合并成「原来没报」会让「监听那时还没开」被误读成「规则漏了」。
+     */
+    originalAbsentReason: "screened_out" | "never_observed" | null;
+};
+export type SubredditMonitorReplayRunDetail = SubredditMonitorReplayRun & {
+    subreddit: string;
+    ruleSetStatus: "draft" | "active" | "retired";
+    /** 与真实账本的差分 —— 回放的产品价值就在这里。 */
+    diff: {
+        /** 当初报过、按新规则不再报的条数。 */
+        wouldStopReporting: number;
+        /**
+         * 当初被筛掉、按新规则会报的条数。
+         * ⚠️ 分母**只算** `screened_out`，⛔ 不含 `never_observed`
+         *（那是「监听那时还没开」，不是规则的功劳）。
+         */
+        wouldNewlyReport: number;
+        /** 当时根本没被这个监听观察到的条数。⛔ 不是「规则漏了」。 */
+        neverObserved: number;
+    };
+    /** 🔴 显式的副作用边界声明：回放没通知任何人、没改账本、没推进水位。 */
+    sideEffects: {
+        notificationsSent: 0;
+        hitsLedgerWritten: false;
+        reportedWatermarkAdvanced: false;
+    };
+};
 export type SubredditMonitorRuleSet = {
     id: string;
     monitorId: string;
@@ -2731,6 +2841,27 @@ export declare class SocialHubClient {
         activated: SubredditMonitorRuleSetDetail;
         retiredRuleSetId: string | null;
     }>;
+    runSubredditMonitorReplay(monitorId: string, body: {
+        /** 省略 = 该监听当前 active 的那版。可显式传 draft(主要用法)。 */
+        ruleSetId?: string;
+        /** ISO 时间串或 Date;窗口按帖子的 postedAt 取,左闭右开,最长 30 天。 */
+        windowStart: string | Date;
+        windowEnd: string | Date;
+        /** 硬顶(默认 500,最大 2000)。撞顶时结果 `truncated=true`。 */
+        limit?: number;
+        note?: string | null;
+    }): Promise<SubredditMonitorReplayRunDetail>;
+    listSubredditMonitorReplays(monitorId: string, params?: {
+        limit?: number;
+    }): Promise<{
+        items: SubredditMonitorReplayRun[];
+    }>;
+    getSubredditMonitorReplay(monitorId: string, replayRunId: string, params?: {
+        decision?: SubredditMonitorReplayDecision;
+        limit?: number;
+    }): Promise<SubredditMonitorReplayRun & {
+        results: SubredditMonitorReplayHit[];
+    }>;
     /** 停用当前版本 ⇒ 该监听回到「不设关键词门」,报告**恢复全量新帖**。 */
     retireSubredditMonitorRuleSet(monitorId: string, ruleSetId: string): Promise<{
         ok: boolean;