@geoly-ai/social-hub-sdk 0.0.51 → 0.0.53

package/dist/index.d.ts

@@ -190,9 +190,99 @@ export type UpdateContentDraftBody = {
     title?: string;
     body?: string;
     status?: string;
+    /**
+     * 目标板块(迁移 0136)。省略 = 不改;`null` = 清空;字符串 = 设置(服务端规范化)。
+     * 属内容身份 → **会** bump 草稿版本(旧内部审核 / 客户批准因此失效)。
+     */
+    subreddit?: string | null;
+    /**
+     * 写作参考 / 归因备注 URL(迁移 0136,原前端字段名 `targetUrl`)。
+     * ⚠️ **不参与发布执行** —— 系统没有 Reddit link post 概念,执行只冻结 title+body。
+     * 不属内容身份 → 单独改它**不** bump 版本、不使既有审核/批准失效。
+     */
+    referenceUrl?: string | null;
     /** Optimistic concurrency: last-loaded version; a mismatch is rejected 409. */
     expectedVersion?: number;
 };
+/**
+ * 本次审核实际采用的**作者关系**(说话人是谁),与 `commentType`(结构位置)正交。
+ *
+ * ⚠️ 一律**服务端派生**。调用方给不了这个值,只能给 {@link ContentReviewAuthorRelationHint};
+ * Hub 按「实际发布账号 handle × 原帖 permalink × Hub 侧帖子快照作者」比对得出。
+ */
+export type ContentReviewAuthorRelation = "post_author" | "other" | "unknown";
+/**
+ * 调用方可给的**非权威提示**。它不是身份声明,也不会被回显为审核结论:
+ * 证据永远覆盖 hint(声称 `other` 但证据显示是作者 → 仍派生 `post_author`);
+ * 声称 `post_author` 而证据证伪 → 422 `AUTHOR_RELATION_MISMATCH`(见
+ * {@link isAuthorRelationMismatchError})。
+ */
+export type ContentReviewAuthorRelationHint = "post_author" | "other";
+/**
+ * 派生依据。`verified_snapshot`=比对了 Hub 侧帖子快照;`verified_live`=预留(未实现);
+ * `mismatch`=显式声称 post_author 但证据证伪(同步 API 走 422,成功响应通常见不到);
+ * `unavailable`=无账号/无 permalink/无快照/作者已删/快照与本次 thread 绑定校验不过 →
+ * `authorRelation=unknown`,按普通基线审核(既不 block 也不给任何 post_author 校准)。
+ */
+export type ContentReviewAuthorRelationEvidence = "verified_snapshot" | "verified_live" | "mismatch" | "unavailable";
+export type ContentReviewThreadInput = {
+    subreddit: string;
+    postTitle: string;
+    postBody?: string;
+    /** `commentType: "reply"` 时必填。 */
+    parentComment?: string;
+    topComments?: string[];
+    subredditToneHint?: string;
+    /**
+     * 所审原帖 permalink —— 作者关系轴的**唯一校验入口**(不给 → `authorRelation=unknown`)。
+     * 服务端 canonicalize 后查帖子快照取作者,并校验快照 subreddit/title 与本次 thread 一致。
+     * SDK 不做 URL 校验,原样透传。
+     */
+    threadPermalink?: string;
+};
+export type ContentReviewRequestInput = {
+    /** 账号 UUID 或 handle;省略=persona-less(ContentOnly)审核。 */
+    accountId?: string;
+    /** 仅一致性校验;无 accountId 时禁止携带。 */
+    personaId?: string;
+    brandContext?: Record<string, unknown>;
+    draft: string;
+    /** 结构位置(调用方声明);与作者关系是两根正交的轴。 */
+    commentType: "top_level" | "reply";
+    /** 非权威提示;服务端证据永远覆盖它。见 {@link ContentReviewAuthorRelationHint}。 */
+    authorRelationHint?: ContentReviewAuthorRelationHint;
+    /** 账号阶段(影响长度/克制度与阈值收紧);不确定就省略,不要传任意字符串。 */
+    stage?: "静默期" | "互动期" | "活跃期";
+    thread: ContentReviewThreadInput;
+    rewrite?: boolean;
+    /** 第几次送审;服务端强制上限 2(防重写循环)。 */
+    attempt?: 1 | 2;
+    traceId?: string;
+};
+export type ContentReviewResponse = {
+    reviewId: string;
+    executionStatus: "completed" | "degraded";
+    verdict: "pass" | "revise" | "block";
+    /**
+     * 服务端派生的权威作者关系。**绝不是**调用方 `authorRelationHint` 的回显 ——
+     * 回显会让「自称 OP」看起来像被系统承认。
+     */
+    authorRelation: ContentReviewAuthorRelation;
+    authorRelationEvidence: ContentReviewAuthorRelationEvidence;
+    score: number;
+    modelScore: number | null;
+    dimensions: Record<string, {
+        score: number;
+        issues: string[];
+    }> | null;
+    optimized: string | null;
+    rationale: string | null;
+    reviewModel: string;
+    rubricVersion: string;
+    thresholdSnapshot: Record<string, unknown>;
+    latencyMs: number;
+    degradedReason: string | null;
+};
 /** 审核目标状态(mirrors contracts REVIEW_TARGET_STATUSES;SDK 不 hard-dep contracts)。 */
 export type ReviewTargetStatusLike = "pending" | "running" | "passed" | "needs_revision" | "blocked" | "degraded" | "superseded";
 export type ListReviewTargetsParams = {
@@ -285,12 +375,28 @@ export type ScheduleCommentDraftBody = {
 };
 export type DeliveryBundleStatusLike = "open" | "closed" | "cancelled";
 /** 客户面列 bundle:brandId 服务端**必填**(客户按 brand 收窄);SDK 类型强制。 */
+/**
+ * `cursor` 与 `offset` **互斥**,用可辨识联合在**编译期**就拒掉错误组合 —— 服务端也会
+ * 400,但把它留到运行时等于让调用方先发一次注定失败的请求。
+ */
 export type ListClientDeliveryBundlesParams = {
     brandId: string;
     status?: DeliveryBundleStatusLike;
     limit?: number;
+} & ({
+    /**
+     * keyset 游标 —— 上一次响应的 `nextCursor` 原样回传。对调用方是**不透明字符串**:
+     * 不要解析或构造,也不要换了 brandId/status 之后复用(游标绑定过滤条件指纹,会 400)。
+     */
+    cursor: string;
+    offset?: never;
+} | {
+    cursor?: undefined;
+    /**
+     * @deprecated 用 `cursor`。offset 分页在并发写入下会重复/跳条(服务端已改 keyset)。
+     */
     offset?: number;
-};
+});
 /** staff 建 bundle。 */
 export type CreateClientDeliveryBundleBody = {
     brandId: string;
@@ -393,6 +499,77 @@ export type ListSubredditWatchlistsParams = {
     /** 按板块名精确查归属(r/ 前缀可省,大小写不敏感)。 */
     subreddit?: string;
 };
+export type ListSubredditMonitorsParams = {
+    limit?: number;
+    offset?: number;
+    /** 缺省 = 全部(含已停止的);服务端只认 "true"/"false" 字符串,方法内负责转换。 */
+    enabled?: boolean;
+    watchlistId?: string;
+};
+/**
+ * 监听配置行(POST 启用的返回)。时间字段一律 `string`(HTTP JSON 里是 ISO 串,
+ * SDK 不代为 `new Date()`,免得调用方拿到「有时 Date 有时 string」的混合类型)。
+ */
+export type SubredditMonitorConfig = {
+    id: string;
+    watchlistId: string;
+    subreddit: string;
+    enabled: boolean;
+    sort: string;
+    fetchLimit: number;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * 监听列表的一行 = 配置行 + 三个派生水位字段。
+ * ⚠️ 这三个字段**只在列表读口有**,POST 启用返回的是裸配置行(见 SubredditMonitorConfig)。
+ */
+export type SubredditMonitorItem = SubredditMonitorConfig & {
+    /** 该监听最近一次观察到帖子的时间;从未观察到 → null。 */
+    lastObservedAt: string | null;
+    /** 最近一轮 run 中该监听**首次观察**到的帖子数。 */
+    newPostsInLatestRun: number;
+    /** 已观察但尚未进入任何送达报告的积压数(报告水位落后的信号)。 */
+    unreportedCount: number;
+};
+export type SubredditMonitorRunStatus = "pending" | "claimed" | "collecting" | "reporting" | "completed" | "degraded" | "failed";
+/** run 列表/摘要读口的形状:**不含** fetchDiagnostics / reportPayload 两个大字段。 */
+export type SubredditMonitorRunSummary = {
+    id: string;
+    scheduleKey: "cron" | "manual";
+    windowStart: string;
+    windowEnd: string;
+    status: SubredditMonitorRunStatus;
+    attempts: number;
+    monitorCount: number;
+    succeededMonitorCount: number;
+    failedMonitorCount: number;
+    observedPostCount: number;
+    newPostCount: number;
+    errorCode: string | null;
+    createdAt: string;
+    completedAt: string | null;
+};
+/** run 详情:摘要 + 只有单条读口才投影的 jsonb 大字段与各阶段时间戳。 */
+export type SubredditMonitorRunDetail = SubredditMonitorRunSummary & {
+    fetchDiagnostics: Record<string, unknown> | null;
+    reportPayload: Record<string, unknown> | null;
+    error: string | null;
+    fetchStartedAt: string | null;
+    fetchCompletedAt: string | null;
+    reportCompletedAt: string | null;
+};
+/** run 列表是 **keyset 分页**(无 offset):游标 = 上一页最后一行的 windowStart + id。 */
+export type ListSubredditMonitorRunsParams = {
+    limit?: number;
+    status?: SubredditMonitorRunStatus;
+    beforeWindowStart?: string;
+    beforeId?: string;
+};
+export type EnableSubredditMonitorBody = {
+    watchlistId: string;
+    fetchLimit?: number;
+};
 export type ListHotPostsParams = {
     limit?: number;
     offset?: number;
@@ -617,6 +794,16 @@ export declare class SocialHubHttpError extends Error {
         body?: string;
     });
 }
+/**
+ * POST /content-review 的 422 稳定错误码:调用方显式声称 `authorRelationHint:"post_author"`,
+ * 但 Hub 侧帖子快照证明发布账号不是该帖作者。
+ *
+ * 这是**硬失败**,不是降级:LLM 一次都不会调用,服务端另落一条安全审计。
+ * 换一个「能验证的」permalink 重试属于 anchor shopping,不要这么做。
+ */
+export declare const CONTENT_REVIEW_AUTHOR_RELATION_MISMATCH: "AUTHOR_RELATION_MISMATCH";
+/** 该错误是否为 {@link CONTENT_REVIEW_AUTHOR_RELATION_MISMATCH}(422 + 稳定 code)。 */
+export declare function isAuthorRelationMismatchError(error: unknown): error is SocialHubHttpError;
 export declare class SocialHubClient {
     private readonly opts;
     constructor(opts: SocialHubClientOptions);
@@ -796,16 +983,31 @@ export declare class SocialHubClient {
     cancelScheduledJob(teamId: string, jobId: string): Promise<unknown>;
     listContentDrafts(teamId: string, params?: {
         limit?: number;
+        offset?: number;
         brandId?: string;
         campaignId?: string;
+        status?: string | string[];
+        /** 目标板块过滤(单值或数组;数组按逗号拼,同字段内 OR)。 */
+        subreddit?: string | string[];
+        search?: string;
     } | number): Promise<{
         items: unknown[];
+        total: number;
+        limit: number;
+        offset: number;
     }>;
     createContentDraft(teamId: string, body: {
         brandId: string;
         campaignId?: string;
         title: string;
         body: string;
+        /** 目标板块(内容语义真源);服务端规范化后落库。省略/null → NULL。 */
+        subreddit?: string | null;
+        /**
+         * 写作参考 / 归因备注 URL:「这篇内容围绕哪个落地页写的」。
+         * ⚠️ **不参与发布执行** —— 系统没有 Reddit link post 概念,执行只冻结 title+body。
+         */
+        referenceUrl?: string | null;
     }): Promise<{
         id: string;
     }>;
@@ -866,9 +1068,13 @@ export declare class SocialHubClient {
         warning?: string;
     }>;
     private clientDeliveryBase;
-    /** GET client-delivery/bundles?brandId=(必填)&status=&limit=&offset= — 客户面 bundle 列表。 */
+    /**
+     * GET client-delivery/bundles?brandId=(必填)&status=&limit=&cursor= — 客户面 bundle 列表。
+     * `nextCursor === null` 表示已到末页;非 null 时原样回传到下次调用的 `cursor`。
+     */
     clientDeliveryListBundles(teamId: string, params: ListClientDeliveryBundlesParams): Promise<{
         items: unknown[];
+        nextCursor?: string | null;
     }>;
     /** GET client-delivery/bundles/:id — 单个 bundle(client 视图脱敏 / staff 完整)。 */
     clientDeliveryGetBundle(teamId: string, bundleId: string): Promise<unknown>;
@@ -1489,7 +1695,36 @@ export declare class SocialHubClient {
         offset?: number;
     }): Promise<{
         items: unknown[];
-        total: number;
+        /**
+         * ⚠️ 0140 起**不再恒为精确值**,必须连着 `totalRelation` 一起读。
+         * `null` = 未计算(keyword 路径)。想判断"还有没有下一页"请用 `hasMore`,
+         * 不要写 `offset + limit >= total` —— 封顶/未知时它会误判成没有下一页。
+         */
+        total: number | null;
+        /** "eq"=精确;"gte"=实际 ≥ total(封顶 10000);"unavailable"=未计算(total 为 null)。 */
+        totalRelation: "eq" | "gte" | "unavailable";
+        /** 权威分页信号:由服务端多取一行得出,与 total 精度无关。 */
+        hasMore: boolean;
+    }>;
+    /**
+     * 评论样本行的**精确 count**(与 list 同一组过滤谓词,无分页、不封顶)。
+     * ⚠️ 故意**不接受 keyword**:keyword 走全文 ILIKE,精确 count 要全表扫
+     * (服务端契约 strict,传了直接 400);keyword 口径请用 listRedditCommentSamples
+     * (totalRelation=unavailable)。
+     * ⚠️ 无过滤时是全表精确 count,属昂贵读——基线用途,**禁止轮询**。
+     * 口径是库内 reddit_comment_samples 行数,不是 Reddit 线程真实评论总数。
+     */
+    countRedditCommentSamples(params?: {
+        postId?: string;
+        subreddit?: string;
+        intent?: string;
+        sentiment?: string;
+        origin?: "hub_collector" | "import";
+    }): Promise<{
+        /** 精确匹配数(不封顶;恒精确,故无 relation 字段)。 */
+        count: number;
+        /** 采样口径恒为部分样本。 */
+        sampleMode: "partial_sample";
     }>;
     dispatchRedditCommentCapture(body: {
         permalinks: string[];
@@ -1625,6 +1860,52 @@ export declare class SocialHubClient {
         ok: boolean;
     }>;
     deleteSubredditWatchlist(watchlistId: string): Promise<void>;
+    listSubredditMonitors(params?: ListSubredditMonitorsParams): Promise<{
+        items: SubredditMonitorItem[];
+        total: number;
+        /** 最近一轮 run(全局,一轮覆盖所有监听);从未跑过 → null。 */
+        latestRun: SubredditMonitorRunSummary | null;
+        limit: number;
+        offset: number;
+    }>;
+    /**
+     * 加入监听(**幂等**):同一 watchlist 已停止的会被重新启用,不新建行 ——
+     * observation ledger 因此保留,重启后已报告过的帖子不会重复报告。
+     */
+    enableSubredditMonitor(body: EnableSubredditMonitorBody): Promise<SubredditMonitorConfig>;
+    /**
+     * 停止监听:DELETE 语义但服务端做**软停**(enabled=false),不删 observation ledger。
+     * 幂等 —— 本来就没在监听时返回 `{ ok: true, updated: false }`,不是 404。
+     */
+    /**
+     * 停止监听。默认是**软停**(`enabled=false`):保留观察 ledger,重新启用后已经报告过的
+     * 帖子不会被再报一遍。
+     *
+     * `purge: true` 是另一个动作 —— **连历史观察一起硬删**。只有在要删掉整个 watchlist 时
+     * 才需要:monitor 配置对 watchlist 的外键是 `ON DELETE RESTRICT`,不先 purge 就删不掉
+     * watchlist(服务端会返回 409 并提示走这条路)。
+     */
+    disableSubredditMonitor(watchlistId: string, options?: {
+        purge?: boolean;
+    }): Promise<{
+        ok: boolean;
+        updated: boolean;
+        purged?: boolean;
+    }>;
+    /** run 列表:keyset 分页,翻页用上一页最后一行的 windowStart + id 当游标。 */
+    listSubredditMonitorRuns(params?: ListSubredditMonitorRunsParams): Promise<{
+        items: SubredditMonitorRunSummary[];
+        hasMore: boolean;
+    }>;
+    /** run 详情:唯一会带回 fetchDiagnostics / reportPayload 两个大字段的读口。 */
+    getSubredditMonitorRun(runId: string): Promise<SubredditMonitorRunDetail>;
+    /** 手工触发一轮(202 入队)。没有任何启用中的监听时服务端返回 400,不制造空跑 run。 */
+    runSubredditMonitors(): Promise<{
+        status: string;
+        monitors: number;
+        jobId?: string;
+        warning?: string;
+    }>;
     listHotPosts(params?: ListHotPostsParams): Promise<{
         items: HotPostListItem[];
         total: number;
@@ -1762,9 +2043,16 @@ export declare class SocialHubClient {
     sessionActiveTeam(body: {
         teamId: string;
     }): Promise<unknown>;
+    /**
+     * 管理员替他人重置密码。需要**不受限的交互式 admin 会话**(role=admin 的 api_key
+     * 不行),且不能重置自己(自助改密走 `PUT /v1/auth/password`,它校验旧密码)。
+     *
+     * `userId` / `email` **恰好给一个**。原来的 `teamId` 参数已删除:密码是用户级全局
+     * 凭证,团队参数从来没有限制过影响范围,只是误导。
+     */
     sessionSetPassword(body: {
-        email: string;
-        teamId?: string;
+        userId?: string;
+        email?: string;
         password: string;
     }): Promise<unknown>;
     sessionUpdateProfile(body: {
@@ -1912,25 +2200,13 @@ export declare class SocialHubClient {
     /**
      * 评论内容复审:独立 LLM 六维评审+服务端权威计分。
      * executionStatus=degraded 时 verdict 不可作为权威判定,调用方应降级本地自审。
+     *
+     * 作者关系轴:响应里的 `authorRelation` / `authorRelationEvidence` 是**服务端派生**的
+     * (见 {@link ContentReviewAuthorRelation}),请求里的 `authorRelationHint` 只是提示。
+     * 声称 `post_author` 而证据证伪 → 422 `AUTHOR_RELATION_MISMATCH`
+     * ({@link isAuthorRelationMismatchError})。
      */
-    contentReview(teamId: string, body: Record<string, unknown>): Promise<{
-        reviewId: string;
-        executionStatus: "completed" | "degraded";
-        verdict: "pass" | "revise" | "block";
-        score: number;
-        modelScore: number | null;
-        dimensions: Record<string, {
-            score: number;
-            issues: string[];
-        }> | null;
-        optimized: string | null;
-        rationale: string | null;
-        reviewModel: string;
-        rubricVersion: string;
-        thresholdSnapshot: Record<string, unknown>;
-        latencyMs: number;
-        degradedReason: string | null;
-    }>;
+    contentReview(teamId: string, body: ContentReviewRequestInput | Record<string, unknown>): Promise<ContentReviewResponse>;
     /** 帖子审核(发帖前质量闸;与评论审核独立 rubric/七维/模型 key)。 */
     postReview(teamId: string, body: Record<string, unknown>): Promise<{
         reviewId: string;