@geoly-ai/social-hub-sdk 0.1.12 → 0.1.13

package/dist/index.d.ts

@@ -132,6 +132,8 @@ export type ListCalendarEntriesParams = {
     from?: string;
     to?: string;
     limit?: number;
+    /** 服务端上限 200;超过就得靠它翻页,别用时间窗二分绕(会漏)。 */
+    offset?: number;
 };
 /** Body for PATCH /calendar-entries/:id */
 export type UpdateCalendarEntryBody = {
@@ -196,6 +198,12 @@ export type ListRedditPostSnapshotsParams = {
     repostType?: string;
     containsBrandKeyword?: "true" | "false" | "unset";
     primaryProduct?: string;
+    /**
+     * 序列号闭区间 `seqNoMin <= seqNo <= seqNoMax`(两端各自可选)。
+     * 任一端给定时,`seqNo` 为 null 的行都会落选;min > max 是 400。
+     */
+    seqNoMin?: number;
+    seqNoMax?: number;
     /** 时间段(与 stats 同口径:COALESCE(postedAt, capturedAt));dateFrom/dateTo 优先。 */
     range?: number | "all";
     dateFrom?: string;
@@ -215,6 +223,9 @@ export type RedditPostSnapshotStatsParams = {
     repostType?: string;
     containsBrandKeyword?: "true" | "false" | "unset";
     primaryProduct?: string;
+    /** 序列号闭区间(与列表同口径)。 */
+    seqNoMin?: number;
+    seqNoMax?: number;
     range?: number | "all";
     /** Custom period bounds (YYYY-MM-DD, inclusive). Take precedence over range. */
     dateFrom?: string;
@@ -732,6 +743,173 @@ export type SubredditMonitorConfig = {
     fetchLimit: number;
     createdAt: string;
     updatedAt: string;
+    /** 当前生效的关键词规则集(0168);null = **不设关键词门**,报告放行全部新帖。 */
+    activeRuleSetId?: string | null;
+    activeRuleSetVersion?: number | null;
+    /** 该监听的回看窗口(分钟)。无 active 规则集 → 720(12h)。 */
+    lookbackMinutes?: number;
+};
+export type SubredditMonitorRuleScope = "title" | "body" | "both";
+/**
+ * `word` 带词边界(🔴 `art` 不会命中 `earth`);`substring` 明确放弃边界;
+ * `phrase` 词序固定、中间允许任意标点换行。
+ * ⚠️ CJK 没有词边界概念,`word` 在 CJK 上退化为子串 —— 否则「咖啡」永远匹配不上「咖啡机」。
+ */
+export type SubredditMonitorMatchMode = "word" | "substring" | "phrase";
+export type SubredditMonitorKeywordRuleInput = {
+    /** 原样字面值;服务端归一化(NFKC / 去重音 / 小写)后才进唯一键。 */
+    term: string;
+    scope?: SubredditMonitorRuleScope;
+    matchMode?: SubredditMonitorMatchMode;
+    /** 只影响卡片里命中词的展示顺序,不影响是否命中(本期只做 include)。 */
+    weight?: number;
+    /** 品牌词导入的**来源溯源**;⛔ 不建立同步语义。 */
+    sourceBrandKeywordId?: string | null;
+    sourceBrandKeywordValue?: string | null;
+};
+export type SubredditMonitorKeywordRule = Required<Pick<SubredditMonitorKeywordRuleInput, "term">> & {
+    id: string;
+    ruleSetId: string;
+    normalizedTerm: string;
+    scope: SubredditMonitorRuleScope;
+    /** 本期只有 `include`(排除词是 P2,契约与 DDL 层都表达不出来)。 */
+    polarity: "include";
+    matchMode: SubredditMonitorMatchMode;
+    weight: number;
+    sourceBrandKeywordId: string | null;
+    sourceBrandKeywordValue: string | null;
+};
+export type SubredditMonitorRuleSet = {
+    id: string;
+    monitorId: string;
+    version: number;
+    /** 🔴 `active` 之后不可原地修改,只能新建版本。`retired` 是终态。 */
+    status: "draft" | "active" | "retired";
+    lookbackMinutes: number;
+    /** 激活时物化的规则指纹;draft 恒为 null。 */
+    ruleHash: string | null;
+    note: string | null;
+    ruleCount: number;
+    createdBy: string | null;
+    activatedBy: string | null;
+    retiredBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    activatedAt: string | null;
+    retiredAt: string | null;
+};
+export type SubredditMonitorRuleSetDetail = SubredditMonitorRuleSet & {
+    rules: SubredditMonitorKeywordRule[];
+};
+/**
+ * 近义词扩展集（0169）。🔴 **固化的**词集 —— approved 之后内容不可原地改。
+ *
+ * ⛔ 它**不参与运行时匹配**：approved 的词要被显式**物化**（复制）成真实的
+ * keyword rule 行才会生效。生产匹配路径上没有任何即时展开。
+ */
+export type SubredditMonitorExpansionSet = {
+    id: string;
+    monitorId: string;
+    baseTerm: string;
+    normalizedBaseTerm: string;
+    /** BCP-47 风格；`und` = 未指定。同一原词在不同语言下各批一套。 */
+    language: string;
+    /** 🔴 固化的扩展词。approved 之后一个字都改不了。 */
+    expansions: Array<{
+        term: string;
+        normalizedTerm: string;
+    }>;
+    expansionCount: number;
+    /** 固化内容的指纹；激活规则集时会被折进 `ruleHash` 的内容摘要。 */
+    contentHash: string;
+    model: string | null;
+    promptVersion: string | null;
+    generatedAt: string | null;
+    /**
+     * 🔴 `proposed` 进不了任何 active 规则集。
+     * `retired` 有两种来历：从 `proposed` 来是**否决**（`approvedAt` 恒为 null，
+     * 永远进不了 active）；从 `approved` 来是**下架**（`approvedAt` 仍在，
+     * 已复制出去的规则行不受影响）。两者只有 `approvedAt` 分得开。
+     */
+    status: "proposed" | "approved" | "retired";
+    approvedBy: string | null;
+    approvedAt: string | null;
+    retiredBy: string | null;
+    retiredAt: string | null;
+    reviewNote: string | null;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * 标签 spec / taxonomy（0169，系统级）。
+ * ⚠️ `taxonomyVersion` **全局唯一** —— 标签行的唯一键带的是它。
+ */
+export type SubredditMonitorLabelSpec = {
+    id: string;
+    version: number;
+    status: "draft" | "active" | "retired";
+    taxonomyVersion: string;
+    /** 稳定 key 白名单。模型自创的 key 一律丢弃。 */
+    labelKeys: string[];
+    promptVersion: string;
+    model: string | null;
+    temperature: number | null;
+    specHash: string | null;
+    note: string | null;
+    createdBy: string | null;
+    activatedBy: string | null;
+    retiredBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    activatedAt: string | null;
+    retiredAt: string | null;
+};
+export type SubredditMonitorDryRunResult = {
+    monitorId: string;
+    ruleSetId: string;
+    ruleSetVersion: number;
+    ruleSetStatus: "draft" | "active" | "retired";
+    subreddit: string;
+    lookbackMinutes: number;
+    /**
+     * 样本量。⚠️ 必须先看它:`sampled === 0` 时「0 命中」说明的是**没有样本**
+     * (板块太冷 / 库里没这段时间的数据),不是「规则太窄」—— 两者在结果列表里长得一样。
+     */
+    sampled: number;
+    matched: number;
+    /** 正文拿不到、判不了的条数。**不算不命中**,上线后会照发并在卡片上标注。 */
+    indeterminate: number;
+    screenedOut: number;
+    /** 逐词命中数:一眼看出哪个词过宽(几乎命中所有帖子)。 */
+    termHitCounts: Array<{
+        term: string;
+        count: number;
+    }>;
+    /** 一次都没命中的词:配错/拼错的第一手信号。 */
+    unusedTerms: string[];
+    results: Array<{
+        permalink: string;
+        title: string | null;
+        postedAt: string | null;
+        score: number | null;
+        commentsCount: number | null;
+        decision: "matched" | "indeterminate" | "no_match";
+        matchedTerms: string[];
+        matchedFields: Array<"title" | "body">;
+        evidence: Array<{
+            ruleId: string;
+            term: string;
+            field: "title" | "body";
+            matchMode: SubredditMonitorMatchMode;
+            weight: number;
+            start: number;
+            end: number;
+            snippet: string;
+        }>;
+        bodyAvailability: "present" | "absent_link_post" | "missing";
+        indeterminateReason: "body_missing" | null;
+    }>;
 };
 /**
  * 监听列表的一行 = 配置行 + 三个派生水位字段。
@@ -2529,6 +2707,177 @@ export declare class SocialHubClient {
         jobId?: string;
         warning?: string;
     }>;
+    listSubredditMonitorRuleSets(monitorId: string, params?: {
+        status?: "draft" | "active" | "retired";
+        limit?: number;
+    }): Promise<{
+        items: SubredditMonitorRuleSet[];
+    }>;
+    getSubredditMonitorRuleSet(monitorId: string, ruleSetId: string): Promise<SubredditMonitorRuleSetDetail>;
+    /** 新建 draft 版本(可带初始规则)。**不会自动激活** —— 激活是单独的显式动作。 */
+    createSubredditMonitorRuleSet(monitorId: string, body?: {
+        /** 有限枚举:720(12h)/ 1440(24h)。run 窗口取所有启用监听中最长的一档。 */
+        lookbackMinutes?: 720 | 1440;
+        note?: string | null;
+        rules?: SubredditMonitorKeywordRuleInput[];
+    }): Promise<SubredditMonitorRuleSetDetail>;
+    /** 整批替换 draft 的规则。非 draft → 409(active 版本不可原地改)。 */
+    replaceSubredditMonitorRules(monitorId: string, ruleSetId: string, body: {
+        rules: SubredditMonitorKeywordRuleInput[];
+        lookbackMinutes?: 720 | 1440;
+    }): Promise<SubredditMonitorRuleSetDetail>;
+    /** 激活:当前 active 版本自动 retire。空规则集会被拒(400)。 */
+    activateSubredditMonitorRuleSet(monitorId: string, ruleSetId: string): Promise<{
+        activated: SubredditMonitorRuleSetDetail;
+        retiredRuleSetId: string | null;
+    }>;
+    /** 停用当前版本 ⇒ 该监听回到「不设关键词门」,报告**恢复全量新帖**。 */
+    retireSubredditMonitorRuleSet(monitorId: string, ruleSetId: string): Promise<{
+        ok: boolean;
+        retired: boolean;
+    }>;
+    /** 删 draft。active/retired 会被服务端拒绝(历史版本必须留痕)。 */
+    deleteSubredditMonitorRuleSetDraft(monitorId: string, ruleSetId: string): Promise<{
+        ok: boolean;
+        deleted: boolean;
+    }>;
+    /**
+     * 🔴 **试跑**:拿该板块过去 lookback 内的历史帖子跑一遍规则,看会命中什么。
+     * **只读:不写命中账本、不推进水位、不发任何通知。**
+     * 没有它,配关键词就是盲填 —— 要等下一轮 cron 才知道效果,而一个宽词的代价是
+     * 负责人被刷屏一整天。`termHitCounts` / `unusedTerms` 是判断词过宽/拼错的直接信号。
+     */
+    dryRunSubredditMonitorRules(monitorId: string, ruleSetId: string, body?: {
+        lookbackMinutes?: 720 | 1440;
+        limit?: number;
+        /** 默认 false —— 运营需要看到「没命中的长什么样」才能判断词是不是配窄了。 */
+        matchedOnly?: boolean;
+    }): Promise<SubredditMonitorDryRunResult>;
+    /**
+     * 从品牌词取**导入候选**(只读)。
+     * ⚠️ 语义是**快照复制**,不是订阅:导入后品牌词再变,已激活的规则集不会跟着变
+     * (响应里的 `semantics` 字段把这一点写死)。要跟进就再导一次并新建版本。
+     */
+    listSubredditMonitorBrandKeywordCandidates(monitorId: string, params?: {
+        brandIds?: string[];
+        limit?: number;
+    }): Promise<{
+        monitorId: string;
+        watchlistId: string;
+        brandIds: string[];
+        semantics: "snapshot_copy_not_synced";
+        items: Array<{
+            brandKeywordId: string;
+            brandId: string;
+            keyword: string;
+            weight: number;
+            kind: string;
+        }>;
+    }>;
+    listSubredditMonitorExpansionSets(monitorId: string, params?: {
+        status?: "proposed" | "approved" | "retired";
+        limit?: number;
+    }): Promise<{
+        items: SubredditMonitorExpansionSet[];
+    }>;
+    getSubredditMonitorExpansionSet(monitorId: string, expansionSetId: string): Promise<SubredditMonitorExpansionSet>;
+    /** 人工录入候选词表（provider 没配时的路径）。产出恒为 `proposed`。 */
+    createSubredditMonitorExpansionSet(monitorId: string, body: {
+        baseTerm: string;
+        language?: string;
+        terms: string[];
+        model?: string | null;
+        promptVersion?: string | null;
+    }): Promise<SubredditMonitorExpansionSet>;
+    /**
+     * 🔴 **离线生成**候选（走仓内统一 llm-review runner）。产出恒为 `proposed`。
+     * provider 没配 ⇒ 409（功能未启用，可改用 `createSubredditMonitorExpansionSet`
+     * 手工录词），⛔ 不是 500。
+     */
+    generateSubredditMonitorExpansion(monitorId: string, body: {
+        baseTerm: string;
+        language?: string;
+    }): Promise<SubredditMonitorExpansionSet & {
+        nextStep: string;
+    }>;
+    /** 批准。🔴 批准之后**内容就冻住了**（DB 焊死）—— 这是「固化」的落点。 */
+    approveSubredditMonitorExpansionSet(monitorId: string, expansionSetId: string, body?: {
+        reviewNote?: string | null;
+    }): Promise<{
+        ok: boolean;
+        approved: boolean;
+    }>;
+    /**
+     * 否决 / 下架。⚠️ 两者共用一条状态转移但痕迹不同：
+     * `proposed → retired` 是**否决**（此后永远进不了 active 规则集）；
+     * `approved → retired` 是**下架**（已复制出去的规则行不受影响 —— 它们拿的是拷贝）。
+     */
+    retireSubredditMonitorExpansionSet(monitorId: string, expansionSetId: string, body?: {
+        reviewNote?: string | null;
+    }): Promise<{
+        ok: boolean;
+        retired: boolean;
+    }>;
+    /** 删候选。approved/retired 会被服务端拒绝（审核过的必须留痕）。 */
+    deleteSubredditMonitorExpansionSet(monitorId: string, expansionSetId: string): Promise<{
+        ok: boolean;
+        deleted: boolean;
+    }>;
+    /**
+     * 🔴 **物化**：把 approved 的扩展词复制成 draft 规则集里的真实规则行。
+     * ⚠️ 物化 ≠ 生效 —— 之后还要显式 `activateSubredditMonitorRuleSet`。
+     * ⚠️ 点名的扩展集里有未批准的 ⇒ 409（⛔ 不静默少物化几条）。
+     */
+    applyExpansionsToRuleSet(monitorId: string, ruleSetId: string, body?: {
+        expansionSetIds?: string[];
+    }): Promise<{
+        ruleSetId: string;
+        inserted: number;
+        skippedDuplicate: number;
+        appliedSets: Array<{
+            expansionSetId: string;
+            baseTerm: string;
+            contentHash: string;
+            terms: number;
+        }>;
+        /**
+         * 🔴 被跳过的扩展集会**显式报出来**（原词不在这个 draft 里）。
+         * ⛔ 不静默少物化 —— 那会让你以为词已经生效了，而卡片上什么都不会变。
+         */
+        skippedSets: Array<{
+            expansionSetId: string;
+            baseTerm: string;
+            reason: "base_term_not_in_rule_set";
+        }>;
+        semantics: "materialized_copy_into_draft_not_active";
+    }>;
+    listSubredditMonitorLabelSpecs(params?: {
+        status?: "draft" | "active" | "retired";
+        limit?: number;
+    }): Promise<{
+        items: SubredditMonitorLabelSpec[];
+    }>;
+    createSubredditMonitorLabelSpec(body: {
+        taxonomyVersion: string;
+        labelKeys: string[];
+        promptVersion: string;
+        model?: string | null;
+        temperature?: number | null;
+        note?: string | null;
+    }): Promise<SubredditMonitorLabelSpec>;
+    activateSubredditMonitorLabelSpec(specId: string): Promise<{
+        activated: SubredditMonitorLabelSpec;
+        retiredSpecId: string | null;
+    }>;
+    /** ⚠️ 停用 = 标签功能整体关闭（卡片不再显示标签行）。 */
+    retireSubredditMonitorLabelSpec(specId: string): Promise<{
+        ok: boolean;
+        retired: boolean;
+    }>;
+    deleteSubredditMonitorLabelSpecDraft(specId: string): Promise<{
+        ok: boolean;
+        deleted: boolean;
+    }>;
     listHotPosts(params?: ListHotPostsParams): Promise<{
         items: HotPostListItem[];
         total: number;